Skip to content

Latest commit

 

History

History
115 lines (79 loc) · 4.29 KB

CONTRIBUTING.md

File metadata and controls

115 lines (79 loc) · 4.29 KB
Raw

Contributing to jsii

We welcome contributions of any kind.

This section includes information for contributors.

Development Environment

Since this repo produces artifacts for multiple programming languages using jsii, it relies on the following toolchains:

Our CI/CD uses the "superchain" image from aws-delivlib.

This image can also be used locally like this (note that initial build may take quite some time):

$ git clone git@github.com:awslabs/aws-delivlib.git
$ cd aws-delivlib/superchain
$ docker build -t superchain .
$ IMAGE=superchain

This will get you into an interactive docker shell:

$ cd jsii # go to the root of the jsii repo
$ docker run --net=host -it -v $PWD:$PWD -w $PWD ${IMAGE}

You can then run ./build.sh as described below.

Bootstrapping

The project is managed as a monorepo using lerna.

  1. Check out this repository.
  2. Run ./build.sh to install lerna, bootstrap the repo and perform an initial build + test cycle.

Workflow

All modules within this repository have the following scripts:

  • build - builds the module (usually runs the TypeScript compiler).
  • watch - runs tsc -w which picks up changes and builds them progressively.
  • test - uses nodeunit test/test.*.js to run all unit tests.
  • package - emits publishable artifacts to dist/<lang>

Each one of these scripts can be executed either from the root of the repo using npx lerna run <script> --scope <package> or from individual modules using npm run <script>.

Bump

To bump the version of this repository, use the ./bump.sh script.

Packaging and Bundling

This repository emits artifacts in multiple languages. The pack.sh and bundle.sh scripts are used to prepare the repository for publishing.

Each module that needs to be published implements an npm script called package which emits publishable artifacts to dist/<lang> (e.g. dist/dotnet for NuGet, dist/js for npm, dist/java for Maven Central). All those "dist" directories are merged into a single .zip file that is later on used in our CI/CD publishing tasks. Each lang directory is published to the respective repository.

Implementing Language Bindings

jsii language bindings consist of two main components:

  1. A runtime client library: a library implemented for each language. This library is responsible to manage the child jsii-runtime process and interact with the jsii-kernel.
  2. jsii-pacmak generator: extend the jsii-pacmak project to be able to generate proxy classes for a jsii module.

This section can definitely use some additional information.

Runtime Client Library

The runtime client library should be implemented as a module under packages/jsii-<lang>-runtime.

The jsii runtime client library usually includes the following components:

  • Child process manager: responsible to start/stop the jsii-runtime child process.
  • Protocol layer: implements the STDIN/STDOUT protocol that interacts with the jsii-runtime.
  • Proxy layer: includes base classes and serialization utilities to implement the generated proxy classes.

More documentation should be added here. In the meantime, refer to the Java implementation as a reference:

Package Generator

The pacmak code generator should be implemented under jsii-pacmak/lib/targets.

The java target is a good example to work from.