Generating Code

In order to used the messages defined in NanoPack schemas, they must be first compiled to the desired programming languages via nanoc (pronounced na-nock), a codegen tool provided by NanoPack.

Prerequisites

nanoc requires the specified code formatter to be installed. nanoc uses the appropriate formatter to format code generated by it.

• C++: clang-format: available as part of Clang.
• Swift: swift-format: available here
• TypeScript: prettier will be used via npx.

Download

Pre-built binaries of nanoc are published as GitHub releases. Put the binary in a directory that is in PATH, or add the directory it is in to PATH, then it is ready to go.

Note

Make sure the installed binaries for the formatters are added to PATH so that nanoc can find it.

Building nanoc

nanoc can also be built from the source code, which requires:

• Go 1.20 or higher (install link)

Clone the nanoc repository here:

Cloning nanoc...

git clone https://github.com/poly-gui/nanoc.git

Change into the nanoc directory:

cd nanoc

Then run the installation command:

go install nanoc/cmd/nanoc

This tells Go to compile the project, then move the output binary to a directory where all the Go binaries are installed in.

The nanoc command should now be available. If not, make sure the directory to where Go installs binaries is in PATH. To add it to PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Note

If GOBIN is set manually, make sure GOBIN is in PATH also.

For non-Go developers, this is probably not applicable.

Usage

This is an overview of the nanoc command:

nanoc --language=[ts|swift|c++] [--factory-out=path] [--namespace=My.Nsp] [...input-files]

Argument	Description
language	(Required) The programming language the generated code should be in
factory-out	(Optional) The directory where the message factory code file should be put in
namespace	(Optional) The namespace under which the generated code should be. Use dot notation, e.g. My.Message
basedir	(Relative) path to the root directory that contains all the schema files. The directory structure of basedir will be preserved in the output directory.
outdir	(Relative) path to the directory in which generated code files should be placed. The directory structure of basedir is preserved.
input-files	A space-delimited list of relative/absolute paths to the schema files that should be processed. Ignored if basedir is specified

Note

If basedir and outdir is specified, nanoc will automatically scan for all schema files, so you don’t have to specify them manually.

What is the message factory?

The message factory file contains a factory function that creates the correct type of message given a NanoPack-formatted buffer and the type ID of the message. Its usage is described in detail in the language guides

Output

nanoc will put the generated files next to each schema file. For example, nanoc will put the TypeScript code for src/MySchema.yml in src/my-schema.ts

Every nanoc generated file will have an extension .np right before the real file extension: .np.ts, .np.swift, .np.cxx, etc.

Instead of specifying every schema file that you want processed, you can specify basedir and outdir, If basedir and outdir is specified, the files will be placed in outdir following the structure of basedir.

Example

Consider the following files in a hypothetical src directory, and suppose the current working directory is where the src directory resides.

• MessageA.np.yml
• MessageB.np.yml

To compile the two schemas to TypeScript:

nanoc --language=ts ./src/MessageA.yml ./src/MessageB.yml

nanoc will produce two files, message-a.np.ts and message-b.np.ts. Now, the src directory will contain the following files:

• MessageA.np.yml
• message-a.np.ts
• MessageB.np.yml
• message-b.np.ts

---

Now, let’s consider a directory called schemas that contains the following schemas:

schemas/
├── MyService/
│   └── MessageB.np.yml
└── MessageA.np.yml

We can run codegen using the following command, assuming schemas is in the current working directory:

nanoc --language=swift --basedir=./schemas --outdir=./generated

This will produce the following files in the generated directory:

generated/
├── MyService/
│   └── MessageB.np.swift
└── MessageA.np.swift

Casing

nanoc will convert the casing of field names and file names to what the convention is for the output language. For example, if the field names in the schema files are in snake_case, nanoc will convert them to camelCase when compiling to Swift or TypeScript. In general, nanoc follows the following table when it comes to casing:

	TypeScript	Swift	C++
Field names	camelCase	camelCase	snake_case
File names	kebab-case	PascalCase	snake_case

Support Library

The generated code assumes that the support library for that language is installed and reachable from the source code. Below is the list of support libraries for each programming language:

• C++: nanopack
• Swift: swift-nanopack
• TypeScript: ts-nanopack