Skip to content

Commit

Permalink
Updates to README (#142)
Browse files Browse the repository at this point in the history 
- Finalized the getting started section
- Added "configuration"
- Updated license

* pacmak: Auto-create/update .npmignore
  • Loading branch information
Elad Ben-Israel committed Aug 6, 2018
1 parent 7d61c9e commit 8416b6a
Show file tree
Hide file tree
Showing 2 changed files with 321 additions and 40 deletions.
274 changes: 254 additions & 20 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,7 @@

__jsii__ allows code in any language to naturally interact with JavaScript classes.

> NOTE: Due to performance of the hosted JavaScript engine and marshaling costs,
__jsii__ modules are likely to be used for development and build tools, as
oppose to performance-sensitive runtime behavior.

For example:
For example, consider the following TypeScript class:

```ts
export class HelloJsii {
Expand All @@ -18,10 +14,19 @@ export class HelloJsii {
}
```

Now, we can use this class from Java:
By compiling our source module using __jsii__, we can now package it as modules
in one of the supported target languages. Each target module has the exact same
API as the source. This allows users of that target language to use `HelloJsii`
like any other class.

> NOTE: Due to performance of the hosted JavaScript engine and marshaling costs,
__jsii__ modules are likely to be used for development and build tools, as
oppose to performance-sensitive runtime behavior.

From Java:

```java
const hello = new HelloJsii();
HelloJsii hello = new HelloJsii();
hello.sayHello("World"); // => Hello, World!
```

Expand All @@ -46,17 +51,32 @@ hello = HelloJsii.new
hello.say_hello 'World' # => Hello, World!
```

# Getting Started
[Here's](#what-kind-of-sorcery-is-this) how it works.

## Getting Started

Let's create our first jsii TypeScript module.

### Initialize the project

Define a `package.json`:

```json
{
"name": "hello-jsii",
"main": "index.js",
"types": "index.d.ts",
"version": "1.0.0",
"license": "Apache-2.0",
"main": "lib/index.js",
"types": "lib/index.d.ts",
"scripts": {
"build": "jsii",
"watch": "jsii -w",
"package": "jsii-pacmak -v"
},
"devDependencies": {
"jsii": "^0.6.0",
"jsii-pacmak": "^0.6.0"
},
"jsii": {
"outdir": "dist",
"targets": {
Expand All @@ -72,18 +92,232 @@ Define a `package.json`:
},
"sphinx": { }
}
}
}
```

What's going on here?

#### `jsii`

The `jsii` section in your `package.json` is the [jsii
configuration](#configuration) for your module. It tells jsii which target
languages to package, and includes additional required information for the
jsii packager (also known as "pacmak").

#### `npm run build``

The `build` script script uses `jsii` to compile your code.

`jsii` wraps the TypeScript compiler (`tsc`) and will compile your .ts files into .js files.

Note that `jsii` is rather opinionated about how the TypeScript compiler is configured (for now),
so it will generate a `tsconfig.json` file for you with the correct options so you an spin up
a TypeScript-supporting IDE. No need to check-in this file.

The `watch` script (optional) will invoke `tsc -w` which will monitor your
filesystem for changes and recompile your .ts files to .js (note that jsii
errors will not be reported in this mode)

#### `npm run package`

The `package` script invokes `jsii-pacmak`, which is the __jsii packager__.

Pacmak will will generate _and compile_ your package to all target languages. The output packages
will be emitted to `outdir` (in the above case `dist`).

The `-v` switch tells pacmak to print some messages.

Run `jsii-pacmak --help` for more options.

#### Required package.json fields

* `license` is required (with SPDX license identifier).
* `main` and `types` are also required and specify the javascript and typescript
declarations entry points of the module.
* `version` is required.

### Module Code

Okay, we are ready to write some code. Create a `lib/index.ts` file:

```ts
export class HelloJsii {
public sayHello(name: string) {
return `Hello, ${name}!`;
}
}
```

### Build

And build your module:

```console
$ npm run build
```

If build succeeds, you will see the resulting .js file (`lib/index.js`) produced by the
TypeScript compiler.

You should also see a `.jsii` file in the root:

```json
{
"fingerprint": "HB39Oy4HWtsnwdRnAFYl+qlmy8Z2tmaGM2KDDe9/hHo=",
"license": "Apache-2.0",
"name": "hello-jsii",
"schema": "jsii/1.0",
"targets": {
"dotnet": {
"namespace": "Acme.Hello"
},
"java": {
"maven": {
"artifactId": "hello-jsii",
"groupId": "com.acme.hello"
},
"package": "com.acme.hello"
},
"js": {
"npm": "hello-jsii"
}
},
"scripts": {
"build": "jsii",
"pacmak": "jsii-pacmak"
"types": {
"hello-jsii.HelloJsii": {
"assembly": "hello-jsii",
"fqn": "hello-jsii.HelloJsii",
"initializer": {
"initializer": true
},
"kind": "class",
"methods": [
{
"name": "sayHello",
"parameters": [
{
"name": "name",
"type": {
"primitive": "string"
}
}
],
"returns": {
"primitive": "string"
}
}
],
"name": "HelloJsii",
"namespace": "hello-jsii"
}
},
"devDependencies": {
"jsii": "^0.5.0-beta",
"@jsii/pacmak": "^0.5.0-beta"
"version": "1.0.0"
}
```

This file includes all the information needed in order to package your module into every
jsii-supported language. It contains the module metadata from `package.json` and a full declaration
of your module's public API.

### Packaging

Okay, now the magic happens:

```console
$ npm run package
[jsii-pacmak] [INFO] Building hello-jsii (java,dotnet,sphinx,npm) into dist
```

Now, if you check out the contents of `dist`, you'll find:

```
├── dotnet
│   └── Acme.Hello
│   ├── Acme.Hello.csproj
│   ├── AssemblyInfo.cs
│   ├── HelloJsii.cs
│   └── hello-jsii-1.0.0.tgz
├── java
│   └── com
│   └── acme
│   └── hello
│   └── hello-jsii
│   ├── 1.0.0
│   │   ├── hello-jsii-1.0.0-javadoc.jar
│   │   ├── hello-jsii-1.0.0-javadoc.jar.md5
│   │   ├── hello-jsii-1.0.0-javadoc.jar.sha1
│   │   ├── hello-jsii-1.0.0-sources.jar
│   │   ├── hello-jsii-1.0.0-sources.jar.md5
│   │   ├── hello-jsii-1.0.0-sources.jar.sha1
│   │   ├── hello-jsii-1.0.0.jar
│   │   ├── hello-jsii-1.0.0.jar.md5
│   │   ├── hello-jsii-1.0.0.jar.sha1
│   │   ├── hello-jsii-1.0.0.pom
│   │   ├── hello-jsii-1.0.0.pom.md5
│   │   └── hello-jsii-1.0.0.pom.sha1
│   ├── maven-metadata.xml
│   ├── maven-metadata.xml.md5
│   └── maven-metadata.xml.sha1
├── js
│   └── hello-jsii@1.0.0.jsii.tgz
└── sphinx
└── hello-jsii.rst
```

These files are ready-to-publish artifacts for each target language. You can
see the npm tarball under `js`, the Maven repo under `java`, the Sphinx .rst file
under `sphinx`, etc.

That's it. You are ready to rock!

## Configuration

jsii configuration is read from the module's `package.json` and includes the following options:

* `targets` - the list of target languages this module will be packaged for. For each
target, you would need to specify some naming information such as namespaces, package manager
coordinates, etc. See [supported targets](#targets) for details.
* `outdir` - the default output directory (relative to package root) for
__jsii-pacmak__. This is where target artifacts are emitted during packaging. Each artifact
will be emitted under `<outdir>/<target>` (e.g. `dist/java`, `dist/js`, etc).

### Targets

The following targets are currently supported:

* `js` - implicit - every module will always have a "js" target (dah!).
* `java` - packages the module as in Java/Maven package. Requires the following config:

```json
{
"java": {
"package": "com.acme.hello",
"maven": {
"groupId": "com.acme.hello",
"artifactId": "hello-jsii"
}
}
}
```

* `dotnet` - packages the module as a .NET/NuGet package. Requires the following config:

```json
{
"dotnet": {
"namespace": "Acme.Hello"
}
}
```

* `sphinx` - produces sphinx documentation for the module. No config is required, but an empty
entry will be needed in order to package this target:

```json
{
"sphinx": { }
}
```


## Features
Expand Down Expand Up @@ -245,7 +479,7 @@ The script will do the following:
3. Create a single .zip file under `dist/jsii-<version>.zip` with all the tarballs.
4. TODO: release to GitHub.

# Language Support
# Adding Target Languages

jsii Language support consists of:

Expand Down Expand Up @@ -281,7 +515,7 @@ library artifacts in a way that they can consumed locally.

## License

Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.

See [LICENSE](./LICENSE.md) file for license terms.
__jsii__ is distributed under the
[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).

See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for more information.
Loading

0 comments on commit 8416b6a

Please sign in to comment.