Aws-cdk: Packaging for beta releases

[eladb]

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]

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).

Why not install those to ~/.cdk/bin as well (instead of /usr/local/bin), if the user is going to add that directory to the path anyway?

Yes, you don't technically need the the rest of the CDK install for the Java version, but users won't care about that anyway. "I have the CDK installed" is what they'll think, and they'll have it, and it'll work.

[rix0rrr]

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

java-app

For me (at least) that feels more natural.

[eladb]

Why not install those to ~/.cdk/bin as well (instead of /usr/local/bin), if the user is going to add that directory to the path anyway?

Yes, I'll try to avoid. The challenge is when you use an IDE, you need jsii-runtime to be available. The long-term solution is that we want to actually bundle the runtime as a .js resource into the client library and then only node.js will be an external dependency (which you need anyway for the toolkit). In the short term, I might be able to find some magical Maven incantation that will do the trick.

[RomainMuller]

I'm not certain I like cdk init app-ts, because that looks messy. To a certain extend, I would rather have something similar to how swift package init --type=[empty|library|executable|system-module] is.

So the ergonomics I would like to have is more like:

cdk init --type=[app|library] --language=[ts|java|dotnet|ruby|...]

[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?

[eladb]

cdk init --type=[app|library] --language=[ts|java|dotnet|ruby|...]

Let's not over-engineer this at this point. I really want to keep cdk-init dead simple and stupid. There's a high abuse potential for templating engines and we should be very careful not to cross that line...

[rix0rrr]

cdk init --type=[app|library] --language=[ts|java|dotnet|ruby|...]

I mean, maybe. But we won't have all combinations to start with.

Also, I prefer typescript to ts.

[RomainMuller]

@rix0rrr I think we can also offer aliases ts for typescript; .net for dotnet, ...
And also, available languages could differ by type -- just a matter of giving out a proper error message.

@eladb The way I see this is very simple... --type is a category, --language is a sub-category. That is all. It would still work like it does now, except two-level folder structure instead of one...