@skorfmann/jsii-srcmak
v0.1.374
Published
generate source code in multiple languages from typescript
Downloads
184
Readme
jsii-srcmak
Generates jsii source files for multiple languages from TypeScript.
Usage
This package can be either used as a library or through a CLI.
The library entry point is the srcmak
function:
import { srcmak } from 'jsii-srcmak';
await srcmak(srcdir[, options]);
The CLI is jsii-srcmak
:
$ jsii-srcmak srcdir [OPTIONS]
The srcdir
argument points to a directory tree that includes TypeScript files
which will be translated through jsii to one of the supported languages.
Compile only
If called with no additional arguments, srcmak
will only jsii-compile the source. If compilation fails, it will throw an error. This is a nice way to check if generated typescript code is jsii-compatible:
const srcdir = generateSomeTypeScriptCode();
// verify it is jsii-compatible (throws otherwise)
await srcmak(srcdir);
CLI:
$ jsii-srcmak /source/directory
Python Output
To produce a Python module from your source, use the python
option:
await srcmak('srcdir', {
python: {
outdir: '/path/to/project/root',
moduleName: 'name.of.python.module'
}
});
Or the --python-*
switches in the CLI:
$ jsii-srcmak /src/dir --python-outdir=dir --python-module-name=module.name
- The
outdir
/--python-outdir
option points to the root directory of your Python project. - The
moduleName
/--python-module-name
option is the python module name. Dots (.
) delimit submodules.
The output directory will include a python module that corresponds to the original module. This code depends on the following python modules:
Java Output
To produce a Java module from your source, use the java
option:
await srcmak('srcdir', {
java: {
outdir: '/path/to/project/root',
package: 'hello.world'
}
});
Or the --java-*
switches in the CLI:
$ jsii-srcmak /src/dir --java-outdir=dir --java-package=hello.world
- The
outdir
/--java-outdir
option points to the root directory of your Java project. - The
package
/--java-package
option is the java package name.
The output directory will include a java module that corresponds to the
original module. This code depends on the following maven package (should be defined directly or indirectly in the project's pom.xml
file):
The output directory will also include a tarball [email protected]
that must be bundled in your project.
C# Output
To produce a C# module from your source, use the csharp
option:
await srcmak('srcdir', {
csharp: {
outdir: '/path/to/project/root',
namespace: 'HelloWorld'
}
});
Or the --csharp-*
switches in the CLI:
$ jsii-srcmak /src/dir --csharp-outdir=dir --csharp-namespace=HelloWorld
- The
outdir
/--csharp-outdir
option points to the root directory of your C# project. - The
package
/--csharp-namespace
option is the C# root namespace.
The output directory will include a C# project that corresponds to the original module. This code depends on the following NuGet package (It is already defined as a dependency in the generated project):
The output directory will also include a tarball [email protected]
that must be bundled in your project (It is already included as an embedded resource in the generated project).
Go Output
To produce a Go module from your source, use the golang
option:
await srcmak('srcdir', {
golang: {
outdir: '/path/to/project/root',
moduleName: 'github.com/yourorg/your-root-project',
packageName: 'helloworld'
}
});
Or the --golang-*
switches in the CLI:
$ jsii-srcmak /src/dir --golang-outdir=dir --golang-module="github.com/yourorg/your-root-project" --golang-package="helloworld"
- The
outdir
/--golang-outdir
option points to the root directory of your base Go project (where yourgo.mod
is in, if you have one). - The
moduleName
/--golang-module
option must match the Go module name of the project that includes the generated source code e.g.github.com/yourorg/your-root-project
. This is currently required, because the generated code needs to reference a submodule which is generated in a nested directory (see also upstream issue https://github.com/aws/jsii/issues/2847 for more information). - The
packageName
/--golang-package
is the package in which the generated Go code will be in. It will be placed in the submodule. So the import path becomes e.g.github.com/yourorg/your-root-project/yourpackage
.
The output directory will include a directory named with the packageName
/--golang-package
containing the generated Go code.
This code depends on the following Go module:
which you need to include in your go.mod
:
require github.com/aws/jsii-runtime-go v1.29.0 # update the version to match the jsii version used in your version of jsii-srcmak
Nested output directories
It is also possible to set the outdir
/--golang-outdir
option to a nested directory inside your Go project. For example, if you want to nest the generated code in a directory called generated
.
In that case you need to append the subdirectory to the module name (e.g. github.com/yourorg/your-root-project/generated
):
$ jsii-srcmak /src/dir --golang-outdir=~/projects/your-root-project/generated --golang-module="github.com/yourorg/your-root-project/generated" --golang-package="helloworld"
Your import path will then become e.g. github.com/yourorg/your-root-project/generated/yourpackage
.
Entrypoint
The entrypoint
option can be used to customize the name of the typescript entrypoint (default is index.ts
).
For example, if the code's entry point is under /srcdir/foobar/lib/index.ts
then I can specify:
await srcmak('/srcdir', {
entrypoint: 'foobar/lib/index.ts'
});
Or through the CLI:
$ jsii-srcmak /srcdir --entrypoint lib/main.ts
Dependencies
The deps
option can be used to specify a list of node module directories (must have a package.json
file) which will be symlinked into the workspace when compiling your code.
This is required if your code references types from other modules.
Use this idiom to resolve a set of modules directories from the calling process:
const modules = [
'@types/node', // commonly needed
'foobar' // a node module in *my* closure
];
const getModuleDir = m =>
path.dirname(require.resolve(`${m}/package.json`));
await srcmak('srcdir', {
deps: modules.map(getModuleDir)
});
Or through the CLI:
$ jsii-srcmak /src/dir --dep node_modules/@types/node --dep node_modules/constructs
Contributing
To build this project, you must first generate the package.json
:
npx projen
Then you can install your dependencies and build:
yarn install
yarn build
What's with this name?
It's a silly little pun that stems from another pun: jsii has jsii-pacmak
which stands for "package maker". That's the tool that takes in a .jsii manifest
and produces language-idiomatic packages from it. This tool produces sources
from a .jsii manifest. Hence, "source maker". Yeah, it's lame.
License
Distributed under the Apache 2.0 license.