@@ -88,35 +88,35 @@ The CDK uses [jsii](https://github.com/aws/jsii/) as its primary build system. j
88
88
typescript-compliant source code and produce polyglot libraries, such as, in Java, .NET, Python and Go.
89
89
90
90
The 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 ` .
92
92
The repo also contains the ` tools/ ` directory that holds custom build tooling (modeled as private npm packages)
93
93
specific to the CDK.
94
94
95
95
### Build
96
96
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.
103
100
104
101
``` console
105
- $ cd packages/@ aws-cdk/aws-ec2
106
- $ ../../../ scripts/buildup
102
+ $ cd packages/aws-cdk-lib
103
+ $ ../../scripts/buildup
107
104
```
108
105
109
106
Note: The ` buildup ` command is resumable. If your build fails, you can fix the issue and run ` buildup --resume ` to
110
107
resume.
111
108
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
113
110
114
111
``` console
115
- $ cd packages/@ aws-cdk/aws-ec2
112
+ $ cd packages/aws-cdk-lib
116
113
$ yarn build
117
114
$ yarn test
118
115
```
119
116
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
+
120
120
However, if you wish to build the entire repository, the following command will achieve this.
121
121
122
122
``` console
@@ -137,13 +137,13 @@ Packing involves generating CDK code in the various target languages and packagi
137
137
respective package managers. Once in a while, these will need to be generated either to test the experience of a new
138
138
feature, or reproduce a packaging failure.
139
139
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:
141
141
142
142
``` console
143
143
$ cd < root-of-cdk-repo>
144
144
$ docker run --rm --net=host -it -v $PWD :$PWD -w $PWD jsii/superchain:1-buster-slim
145
- docker$ cd packages/@ aws-cdk/aws-ec2
146
- docker$ ../../../ scripts/foreach.sh --up yarn run package
145
+ docker$ cd packages/aws-cdk-lib
146
+ docker$ ../../scripts/foreach.sh --up yarn run package
147
147
docker$ exit
148
148
```
149
149
@@ -317,12 +317,12 @@ CDK integration tests.
317
317
We've added a watch feature to the CDK that builds your code as you type it. Start this by running ` yarn watch ` for
318
318
each module that you are modifying.
319
319
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:
321
321
322
322
``` console
323
- $ cd packages/@ aws-cdk/aws-ec2
323
+ $ cd packages/aws-cdk-lib
324
324
$ yarn watch & # runs in the background
325
- $ cd packages/@ aws-cdk/aws-iam
325
+ $ cd packages/aws-cdk
326
326
$ yarn watch & # runs in the background
327
327
```
328
328
@@ -637,10 +637,10 @@ The README file contains code snippets written as typescript code. Code snippets
637
637
(such as `` ```ts `` ) will be automatically extracted, compiled and translated to other languages when the
638
638
during the [ pack] ( #pack ) step. We call this feature 'rosetta'.
639
639
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:
641
641
642
642
``` console
643
- $ cd packages/@ aws-cdk/aws-ec2
643
+ $ cd packages/aws-cdk-lib
644
644
$ yarn rosetta:extract --strict
645
645
```
646
646
@@ -696,14 +696,14 @@ cases where some of those do not apply - good judgement is to be applied):
696
696
- Types from the documented module should be ** un-qualified** :
697
697
698
698
``` 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
700
700
Duration .minutes (15 );
701
701
```
702
702
703
703
- Types from other modules should be ** qualified** :
704
704
705
705
``` 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
707
707
const bucket = new s3 .Bucket (this , ' Bucket' );
708
708
// ...rest of the example...
709
709
```
@@ -712,7 +712,7 @@ cases where some of those do not apply - good judgement is to be applied):
712
712
necessary for compilation but unimportant to the example:
713
713
714
714
``` 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
716
716
declare const pipeline: pipelines .CodePipeline ;
717
717
declare const myStage: Stage ;
718
718
pipeline .addStage (myStage );
@@ -766,7 +766,7 @@ Consequently, there are two useful scripts that are built on top of `foreach.sh`
766
766
All linters are executed automatically as part of the build script, ` yarn build ` .
767
767
768
768
They 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 -
770
770
771
771
``` bash
772
772
yarn lint
@@ -878,88 +878,24 @@ $ cdk -a some.app.js synth | $awscdk/scripts/template-deps-to-dot | dot -Tpng >
878
878
879
879
You can use ` find-cycles ` to print a list of internal dependency cycles:
880
880
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
-
893
881
## Running CLI integration tests
894
882
895
883
The CLI package (` packages/aws-cdk ` ) has some integration tests that aren't
896
884
run as part of the regular build, since they have some particular requirements.
897
885
See the [ CLI CONTRIBUTING.md file] ( packages/aws-cdk/CONTRIBUTING.md ) for
898
886
more information on running those tests.
899
887
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
-
932
888
## Building and testing v2 -alpha packages
933
889
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 `
950
894
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.
957
898
958
- ```
959
- <CDK repo root>/scripts/transform.sh --skip-build
960
- cd packages/individual-packages/aws-<service>
961
- yarn build+test
962
- ```
963
899
## Changing Cloud Assembly Schema
964
900
965
901
If you plan on making changes to the ` cloud-assembly-schema ` package, make sure you familiarize yourself with
0 commit comments