Skip to content

Latest commit

 

History

History
108 lines (75 loc) · 4.27 KB

CONTRIBUTING.md

File metadata and controls

108 lines (75 loc) · 4.27 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:

When building on CodeBuild, these toolchains are all included in the superchain docker image. This image can also be used locally as follows:

eval $(aws ecr get-login --no-include-email)
IMAGE=260708760616.dkr.ecr.us-east-1.amazonaws.com/superchain:latest
docker pull ${IMAGE}
docker run --net=host -it -v $PWD:$PWD -w $PWD ${IMAGE}

This will get you into an interactive docker shell. You can then run ./install.sh and ./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/xxx (where "xxx" is the language)

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

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-xxx-runtime (where xxx is the language).

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.