Packaging for beta releases

Let’s work backwards from how we want beta participants to use the CDK.

Installation

Theoretically, this step should only install the toolkit on the system, but since we still don’t have the CDK libraries released into package managers, the installed bundle will also contain a local repository of all modules in all languages. The “magic” will happen in cdk init, which will take care of binding the newly created project to the local copy instead of the package manager (depending on the language).

1. Download a zip from an authenticated URL (GitHub releases would be an idiomatic way to do it, but we can also publish to S3 and have users download using the CLI).
2. Run a setup command which unzips the file and install it under ~/.cdk. Ideally we don’t want any system-level installs (including jsii-runtime), but as a temporary workaround until we bundle the runtime with the java client we can do with a installing jsii-runtime to /usr/local/bin (requires sudo).
3. Ask users to add ~/.cdk/bin to their PATH.

Creating Projects

During beta we expect all CDK projects to be created using cdk init.

Post-beta users will be able to create CDK projects in any way they want and just consume modules idiomatically through their package manager, but this technique should also work.

We should have two types of templates for each supported language:

1. CDK App: defines a user Stack, an App and the build process will synthesize CloudFormation templates for all stacks defined in the app.
2. CDK Library: exports a construct.

TypeScript

For example, cdk init typescript-app will initialize the current directory with a typescript CDK app project and then run npm install to bring in all the deps.

The directory will include:

• package.json file with devDependencies which includes pointers to file:// tarballs installed udner ~/.cdk. The package.json file will include all CDK modules (aws-cdk-xxx). This will make it easier for users to get started, and will also solve the issue of dependency resolution without npm.
• prepare and watch scripts use tsc (not jsii), since this is an app, also requires tsconfig.json.
• cdk.json has { app: node index.js }
• cdk script will run the toolkit cdk.
• prepare script will also invoke cdk synth -o cdk-out or something like that. Which means that building the project will automatically synthesize the templates.

Java

cdk init java-app will initialize the current directory with a java maven project. The pom.xml file will use a system scope (or file:// repository, whichever makes more sense) to point to aws-cdk and jsii-java-runtime packages under ~/.cdk.

The maven project will also include a post-build step that will invoke synthesize and will produce templates to cdk-out (same name as the JS projects, to make it easier for CI/CD to be set up later).

[rix0rrr]

The challenge is when you use an IDE, you need jsii-runtime to be available.

Well yeah, but then all you have to do is start your IDE after updating the PATH. Although I got you, if you start your IDE from a GUI, where does the PATH even come from?

[rix0rrr]

Agreed on all of the rest. As one more note, I think I’d prefer <LANGUAGE>-<TYPE>, so:

typescript-app
java-app

For me (at least) that feels more natural.