software.amazon.awscdk.cli.lib.alpha.package-info Maven / Gradle / Ivy

Go to download
/**
 * AWS CDK CLI Library
 * 
 * ---
 * 

 * 
 * 

 * 

 * 
 * The APIs of higher level constructs in this module are experimental and under active development.
 * They are subject to non-backward compatible changes or removal in any future version. These are
 * not subject to the Semantic Versioning model and breaking changes will be
 * announced in the release notes. This means that while you may use them, you may need to update
 * your source code when upgrading to a newer version of this package.
 * 

 * 
 * 
 * 

 * 
 * 
 * 

 * 
⚠️ Experimental module
 * 
 * This package is highly experimental. Expect frequent API changes and incomplete features.
 * Known issues include:
 * 

 * 

 * JavaScript/TypeScript only\
 * The jsii packages are currently not in a working state.
 * No useful return values\
 * All output is currently printed to stdout/stderr
 * Missing or Broken options\
 * Some CLI options might not be available in this package or broken
 * 
 * 
 * 
Overview
 * 
 * Provides a library to interact with the AWS CDK CLI programmatically from jsii supported languages.
 * Currently the package includes implementations for:
 * 

 * 

 * cdk deploy
 * cdk synth
 * cdk bootstrap
 * cdk destroy
 * cdk list
 * 
 * 
 * 
Setup
 * 
 * 
AWS CDK app directory
 * 
 * Obtain an AwsCdkCli class from an AWS CDK app directory (containing a cdk.json file):
 * 

 * 
 * AwsCdkCli cli = AwsCdkCli.fromCdkAppDirectory("/path/to/cdk/app");
 * 
 * 
 * 
Cloud Assembly Directory Producer
 * 
 * You can also create AwsCdkCli from a class implementing ICloudAssemblyDirectoryProducer.
 * AWS CDK apps might need to be synthesized multiple times with additional context values before they are ready.
 * 

 * The produce() method of the ICloudAssemblyDirectoryProducer interface provides this multi-pass ability.
 * It is invoked with the context values of the current iteration and should use these values to synthesize a Cloud Assembly.
 * The return value is the path to the assembly directory.
 * 

 * A basic implementation would look like this:
 * 

 * 
 * public class MyProducer implements ICloudAssemblyDirectoryProducer {
 *     public Promise produce(Map<String, Object> context) {
 *         App app = App.Builder.create().context(context).build();
 *         Stack stack = new Stack(app);
 *         return app.synth().getDirectory();
 *     }
 * }
 * 
 * 
 * For all features (e.g. lookups) to work correctly, cdk.App() must be instantiated with the received context values.
 * Since it is not possible to update the context of an app, it must be created as part of the produce() method.
 * 

 * The producer can than be used like this:
 * 

 * 
 * AwsCdkCli cli = AwsCdkCli.fromCloudAssemblyDirectoryProducer(new MyProducer());
 * 
 * 
 * 
Commands
 * 
 * 
list
 * 
 * 
 * // await this asynchronous method call using a language feature
 * cli.list();
 * 
 * 
 * 
synth
 * 
 * 
 * // await this asynchronous method call using a language feature
 * cli.synth(SynthOptions.builder()
 *         .stacks(List.of("MyTestStack"))
 *         .build());
 * 
 * 
 * 
bootstrap
 * 
 * 
 * // await this asynchronous method call using a language feature
 * cli.bootstrap();
 * 
 * 
 * 
deploy
 * 
 * 
 * // await this asynchronous method call using a language feature
 * cli.deploy(DeployOptions.builder()
 *         .stacks(List.of("MyTestStack"))
 *         .build());
 * 
 * 
 * 
destroy
 * 
 * 
 * // await this asynchronous method call using a language feature
 * cli.destroy(DestroyOptions.builder()
 *         .stacks(List.of("MyTestStack"))
 *         .build());
 * 
 */
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
package software.amazon.awscdk.cli.lib.alpha;