@@ -88,35 +88,35 @@ The CDK uses [jsii](https://github.com/aws/jsii/) as its primary build system. j
8888typescript-compliant source code and produce polyglot libraries, such as, in Java, .NET, Python and Go.
8989
9090The repo contains ` packages/ ` directory that contains the CDK public modules. The source code for the IAM module in the
91- CDK can be found at the location ` packages/@ aws-cdk/aws-iam ` .
91+ CDK can be found at the location ` packages/aws-cdk-lib /aws-iam ` .
9292The repo also contains the ` tools/ ` directory that holds custom build tooling (modeled as private npm packages)
9393specific to the CDK.
9494
9595### Build
9696
97- The full build of the CDK takes a long time to complete; 1-2 hours depending on the performance of the build machine.
98- However, most first time contributions will require changing only one CDK module, sometimes two. A full build of the
99- CDK is not required in these cases.
100-
101- If you want to work on the ` @aws-cdk/aws-ec2 ` module, the following command will build just the EC2 module and any
102- necessary dependencies.
97+ The full build of all of the packages within the repository can take a few minutes, about 20 when all tests are run.
98+ Most contributions only require working on a single package, usually ` aws-cdk-lib ` . To build this package for the first
99+ time, you can execute the following to build it and it's dependencies.
103100
104101``` console
105- $ cd packages/@ aws-cdk/aws-ec2
102+ $ cd packages/aws-cdk-lib
106103$ ../../../scripts/buildup
107104```
108105
109106Note: The ` buildup ` command is resumable. If your build fails, you can fix the issue and run ` buildup --resume ` to
110107resume.
111108
112- At this point, you can run build and test the ` aws-ec2 ` module by running
109+ At this point, you can run build and test the ` aws-cdk-lib ` module by running
113110
114111``` console
115- $ cd packages/@ aws-cdk/aws-ec2
112+ $ cd packages/aws-cdk-lib
116113$ yarn build
117114$ yarn test
118115```
119116
117+ To cut down on iteration time as you develop, you can run ` yarn watch ` within the ` aws-cdk-lib ` directory to keep
118+ some of the build state in memory and incrementally rebuild as you make changes.
119+
120120However, if you wish to build the entire repository, the following command will achieve this.
121121
122122``` console
@@ -137,12 +137,12 @@ Packing involves generating CDK code in the various target languages and packagi
137137respective package managers. Once in a while, these will need to be generated either to test the experience of a new
138138feature, or reproduce a packaging failure.
139139
140- To package a specific module, say the ` @ aws-cdk/aws-ec2 ` module:
140+ To package a specific module, say the ` aws-cdk-lib ` module:
141141
142142``` console
143143$ cd < root-of-cdk-repo>
144144$ docker run --rm --net=host -it -v $PWD :$PWD -w $PWD jsii/superchain:1-buster-slim
145- docker$ cd packages/@ aws-cdk/aws-ec2
145+ docker$ cd packages/aws-cdk-lib
146146docker$ ../../../scripts/foreach.sh --up yarn run package
147147docker$ exit
148148```
@@ -317,12 +317,12 @@ CDK integration tests.
317317We've added a watch feature to the CDK that builds your code as you type it. Start this by running ` yarn watch ` for
318318each module that you are modifying.
319319
320- For example, watch the EC2 and IAM modules in a second terminal session:
320+ For example, watch the aws-cdk-lib and aws-cdk modules in a second terminal session:
321321
322322``` console
323- $ cd packages/@ aws-cdk/aws-ec2
323+ $ cd packages/aws-cdk-lib
324324$ yarn watch & # runs in the background
325- $ cd packages/@ aws-cdk/aws-iam
325+ $ cd packages/aws-cdk
326326$ yarn watch & # runs in the background
327327```
328328
@@ -637,10 +637,10 @@ The README file contains code snippets written as typescript code. Code snippets
637637(such as `` ```ts `` ) will be automatically extracted, compiled and translated to other languages when the
638638during the [ pack] ( #pack ) step. We call this feature 'rosetta'.
639639
640- You can run rosetta on the EC2 module (or any other module) by running:
640+ You can run rosetta on the aws-cdk-lib module (or any other module) by running:
641641
642642``` console
643- $ cd packages/@ aws-cdk/aws-ec2
643+ $ cd packages/aws-cdk-lib
644644$ yarn rosetta:extract --strict
645645```
646646
@@ -696,14 +696,14 @@ cases where some of those do not apply - good judgement is to be applied):
696696- Types from the documented module should be ** un-qualified** :
697697
698698 ``` ts
699- // An example in the @ aws-cdk/core library, which defines Duration
699+ // An example in the aws-cdk-lib library, which defines Duration
700700 Duration .minutes (15 );
701701 ```
702702
703703- Types from other modules should be ** qualified** :
704704
705705 ``` ts
706- // An example in the @ aws-cdk/core library, using something from @ aws-cdk/aws-s3
706+ // An example in the aws-cdk-lib library, using something from aws-cdk-lib /aws-s3
707707 const bucket = new s3 .Bucket (this , ' Bucket' );
708708 // ...rest of the example...
709709 ```
@@ -712,7 +712,7 @@ cases where some of those do not apply - good judgement is to be applied):
712712 necessary for compilation but unimportant to the example:
713713
714714 ``` ts
715- // An example about adding a stage to a pipeline in the @ aws-cdk/pipelines library
715+ // An example about adding a stage to a pipeline in the aws-cdk-lib /pipelines library
716716 declare const pipeline: pipelines .CodePipeline ;
717717 declare const myStage: Stage ;
718718 pipeline .addStage (myStage );
@@ -766,7 +766,7 @@ Consequently, there are two useful scripts that are built on top of `foreach.sh`
766766All linters are executed automatically as part of the build script, ` yarn build ` .
767767
768768They can also be executed independently of the build script. From the root of a specific package (e.g.
769- ` packages/@ aws-cdk/aws-ec2 ` ), run the following command to execute all the linters on that package -
769+ ` packages/aws-cdk-lib ` ), run the following command to execute all the linters on that package -
770770
771771``` bash
772772yarn lint
@@ -878,88 +878,24 @@ $ cdk -a some.app.js synth | $awscdk/scripts/template-deps-to-dot | dot -Tpng >
878878
879879You can use ` find-cycles ` to print a list of internal dependency cycles:
880880
881- ``` shell
882- $ scripts/find-cycles.sh
883- Cycle: @aws-cdk/aws-iam => @aws-cdk/assert => aws-cdk => @aws-cdk/aws-s3 => @aws-cdk/aws-kms => @aws-cdk/aws-iam
884- Cycle: @aws-cdk/assert => aws-cdk => @aws-cdk/aws-s3 => @aws-cdk/aws-kms => @aws-cdk/assert
885- Cycle: @aws-cdk/aws-iam => @aws-cdk/assert => aws-cdk => @aws-cdk/aws-s3 => @aws-cdk/aws-iam
886- Cycle: @aws-cdk/assert => aws-cdk => @aws-cdk/aws-s3 => @aws-cdk/assert
887- Cycle: @aws-cdk/assert => aws-cdk => @aws-cdk/aws-cloudformation => @aws-cdk/assert
888- Cycle: @aws-cdk/aws-iam => @aws-cdk/assert => aws-cdk => @aws-cdk/util => @aws-cdk/aws-iam
889- Cycle: @aws-cdk/aws-sns => @aws-cdk/aws-lambda => @aws-cdk/aws-codecommit => @aws-cdk/aws-sns
890- Cycle: @aws-cdk/aws-sns => @aws-cdk/aws-lambda => @aws-cdk/aws-codecommit => @aws-cdk/aws-codepipeline => @aws-cdk/aws-sns
891- ```
892-
893881## Running CLI integration tests
894882
895883The CLI package (` packages/aws-cdk ` ) has some integration tests that aren't
896884run as part of the regular build, since they have some particular requirements.
897885See the [ CLI CONTRIBUTING.md file] ( packages/aws-cdk/CONTRIBUTING.md ) for
898886more information on running those tests.
899887
900- ## Building aws-cdk-lib
901-
902- In AWS CDK v2, all stable libraries are packaged into a single monolithic
903- package and published as ` aws-cdk-lib ` . In most cases, you can iterate on a
904- single module's directory as previously described in this document (e.g.
905- ` packages/@aws-cdk/aws-s3 ` ). In some cases, you might need to build
906- ` aws-cdk-lib ` :
907-
908- ```
909- # Generate all of the L1s first. If you have already done a full build in the repository, you can skip this.
910- cd <CDK repo root>/
911- ./scripts/gen.sh
912-
913- # Generate and build `aws-cdk-lib`
914- cd packages/aws-cdk-lib
915- yarn build
916- ```
917-
918- The commands above perform the following steps:
919- 1 . Run ` yarn install ` to install all dependencies
920- 2 . Generate ` .generated.ts ` files in each ` packages/@aws-cdk/aws-<service> `
921- directory. These files contain TypeScript source code for all of the L1 (Cfn)
922- Constructs, and are generated from the [ CloudFormation Resource
923- Specification] ( https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-resource-specification.html ) .
924- 3 . Copy the ` .ts ` source code files from each ` packages/@aws-cdk/aws-<service> `
925- directory to the corresponding ` packages/aws-cdk-lib/aws-<service> `
926- directory.
927- 4 . Compile ` aws-cdk-lib ` .
928-
929- Running unit tests and integration tests still has to be performed in each
930- module's ` packages/@aws-cdk ` directory.
931-
932888## Building and testing v2 -alpha packages
933889
934- In AWS CDK v2, all experimental libraries are published separately with an
935- -alpha suffix. In most cases, you can iterate on a single module's directory as
936- already described in this document (e.g. ` packages/@aws-cdk/aws-amplify ` ). If
937- you need to generate and iterate on the alpha package, here are the steps. The
938- main differences between the alpha package is naming of the package, and import
939- statements.
940-
941- First, make sure the following packages are built:
942- - packages/@aws-cdk/assert
943- - packages/aws-cdk-lib
944- - tools/individual-pkg-gen
945-
946- The following command will create all of the alpha packages by copying files
947- from their source directories under ` packages/@aws-cdk/aws-<service> ` , and it
948- will build and run unit tests for all of them. This is sometimes too much for a
949- developer machine or laptop.
890+ Modules that are not stable are vended separately from ` aws-cdk-lib ` . These packages are found in the
891+ ` packages/@aws-cdk ` directory and are marked ` stability: 'experimental' ` in their package.json files.
892+ This means they will be given the ` alpha ` version from the ` version.v2.json ` when published and they
893+ cannot be taken as dependencies by ` aws-cdk-lib `
950894
951- ```
952- <CDK repo root>/scripts/transform.sh
953- ```
954-
955- To only copy and transform the source files, and then build and test one
956- alpha package at a time, use the following:
895+ Experimental packages are used to develop new constructs and experiment with their APIs before marking
896+ them as stable and including them within ` aws-cdk-lib ` . Once they are included in ` aws-cdk-lib ` , no
897+ more breaking api changes can be made.
957898
958- ```
959- <CDK repo root>/scripts/transform.sh --skip-build
960- cd packages/individual-packages/aws-<service>
961- yarn build+test
962- ```
963899## Changing Cloud Assembly Schema
964900
965901If you plan on making changes to the ` cloud-assembly-schema ` package, make sure you familiarize yourself with
0 commit comments