Skip to main content

CommandLine

Command​

build​

build command builds a next project file or runs all next project files in a directory. It reads the project file and compiles the source files according to the project configuration. The project file is a YAML or JSON file that contains the project Configuration.

Example:

# build all .nextproj files in the current directory
next build

# build the example.nextproj file
next build example.nextproj

# build all .nextproj files in the example directory
next build example/

# build multiple project files or directories
next build example1.nextproj example2.nextproj example
tip

.nextproj is recommended for the Next project file.

grammar​

grammar command generates the default grammar for the next files.

Example:

next grammar # generate the default grammar to the standard output with YAML format
next grammar grammar.yaml # generate the default grammar with YAML format
next grammar grammar.yml # generate the default grammar with YAML format
next grammar grammar.json # generate the default grammar with JSON format
note

The default grammar is generated in YAML format if the file extension is not provided. Currently, the supported file extensions are .json, .yaml, and .yml (alias of .yaml).

version​

version command prints the version of the next compiler. It prints the version of the next compiler and exits the program.

Example:

next version

Output:

next v0.0.4(main: 51864a35de7890d63bfd8acecdb62d20372ca963) built at 2024/09/27T22:58:21+0800 by go1.23.0

Configuration​

.env​

.env represents the custom environment variables for code generation.

Example:

env:
  VERSION: "2.1"
  DEBUG: ""
  NAME: myapp

See the -D flag for more information.

.grammar​

.grammar represents the custom grammar for the next source code.

Example:

grammar: grammar.yaml

See the -g flag for more information.

.head​

.head represents the header comment for generated code.

Example:

head: "Code generated by Next; DO NOT EDIT."

See the -head flag for more information.

.mapping​

.mapping represents the language-specific type mappings and features.

Example:

mapping:
  cpp.vector: "std::vector<%T%>"
  java.array: "ArrayList<%T%>"
  go.map: "map[%K%]%V%"
  python.ext: ".py"
  protobuf.vector: "repeated %T.E%"
  ruby.comment: "# %T%"

See the -M flag for more information.

.output​

.output represents the output directories for generated code of each target language.

Example:

output:
  go: ./output/go
  ts: ./output/ts

See the -O flag for more information.

.solvers​

.solvers represents the custom annotation solver programs for code generation.

Example:

solvers:
  message: "message-type-allocator message-types.json"

See the -X flag for more information.

.sources​

.sources represents the source directories or files.

Example:

sources:
  - demo.next
  - src/next/
.strict​

.strict represents the strict mode of the compiler.

Example:

strict: true

See the -s flag for more information.

.templates​

.templates represents the custom template directories or files for each target language.

Example:

templates:
  go:
    - ./templates/go
    - ./templates/go_extra.npl
  python:
    - ./templates/python.npl

See the -T flag for more information.

.verbose​

.verbose represents the verbosity level of the compiler.

Example:

verbose: 1

See the -v flag for more information.

Flag​

-D​

-D represents the custom environment variables for code generation. The value is a map of environment variable names and their optional values.

Example:

next -D VERSION=2.1 -D DEBUG -D NAME=myapp ...
{{env.NAME}}
{{env.VERSION}}

Output:

myapp
2.1

-M​

-M represents the language-specific type mappings and features. %T%, %T.E%, %N%, %K%, %V% are placeholders replaced with actual types or values. %T.E% is the final element type of a vector or array. It's used to get the element type of multi-dimensional arrays.

Example:

next -M "cpp.vector=std::vector<%T%>" \
     -M "java.array=ArrayList<%T%>" \
     -M "go.map=map[%K%]%V%" \
     -M python.ext=.py \
     -M "protobuf.vector=repeated %T.E%" \
     -M "ruby.comment=# %T%" \
     ...

-O​

-O represents the output directories for generated code of each target language.

Example:

next -O go=./output/go -O ts=./output/ts ...
tip

The {{meta.path}} is relative to the output directory.

-T​

-T represents the custom template directories or files for each target language. You can specify multiple templates for a single language.

Example:

next -T go=./templates/go \
     -T go=./templates/go_extra.npl \
     -T python=./templates/python.npl \
     ...

-X​

-X represents the custom annotation solver programs for code generation. Annotation solvers are executed in a separate process to solve annotations. All annotations are passed to the solver program via stdin and stdout. The built-in annotation next is reserved for the Next compiler.

Example:

next -X message="message-type-allocator message-types.json" ...
tip

In the example above, the message-type-allocator is a custom annotation solver program that reads the message types from the message-types.json file and rewrite the message types to the message-types.json file.

-g​

-g represents the custom grammar for the next source code.

Example:

next -g grammar.yaml ...
note

By default, the compiler uses the built-in grammar for the next source code. You can set a custom grammar file to define a subset of the next grammar. The grammar file is a JSON file that contains rules.

If -s is not set, the compiler will ignore unknown annotations and unknown annotation parameters.

-head​

-head represents the header comment for generated code. The value is a string that represents the header comment for generated code. The default value is an empty string, which means default header comment is used.

Example:

next -head "Code generated by Next; DO NOT EDIT." ...
note

Do not add the comment characters like // or /* */ in the header. Next will add them automatically based on the target language comment style.

-s​

-s represents the strict mode of the compiler. The default value is false, which means the compiler is not in strict mode. The value true enables the strict mode, which is used for strict validation of the next source code, such as unknown annotations and unknown annotation parameters.

Example:

next -s ...

-t​

-t represents the test mode of the compiler. The default value is false, which means the compiler is not in test mode. The value true enables the test mode, which is used for validating but not generating code.

Example:

next -t ...

-v​

-v represents the verbosity level of the compiler. The default value is 0, which only shows error messages. The value 1 shows debug messages, and 2 shows trace messages. Usually, the trace message is used for debugging the compiler itself. Levels 1 (debug) and above enable execution of:

  • print and printf in Next source files (.next).
  • debug in Next template files (.npl).

Example:

next -v 1 ...

Options​

Options represents the options of the Next project. The options is used to mamange the compiler options, such as verbosity, output directories, and custom templates. If the options is provided, you can generate code like this:

next build example.nextproj

The options file is a YAML or JSON (for .json extension) file that contains the compiler options. Here is an example of the options file:

example.nextproj
# This is a next project file.

# Enable the strict mode, like the -s flag
strict: true

# Verbose level, like the -v flag
# 0: quiet, 1: debug, 2: trace
verbose: 1

# Grammar file, like the -g flag
grammar: grammar.yaml

# Variables, like the -d flag
env:
  PROJECT_NAME: demo
  GO_MOD: github.com/next/next/website/example/gen/go

# Output directories for target languages, like the -O flag
output:
  go: gen/go
  java: gen/java
  cpp: gen/cpp
  csharp: gen/csharp
  c: gen/c
  rust: gen/rust/src
  protobuf: gen/protobuf
  js: gen/js
  ts: gen/ts
  python: gen/python
  php: gen/php
  lua: gen/lua

# Templates for target languages, like the -T flag
templates:
  go: [templates/go]
  java: [templates/java]
  cpp: [templates/cpp]
  csharp: [templates/csharp]
  c: [templates/c]
  rust: [templates/rust]
  protobuf: [templates/protobuf]
  js: [templates/js]
  ts: [templates/ts]
  python: [templates/python]
  php: [templates/php]
  lua: [templates/lua]

# Features or types mapping, like the -M flag
mapping:
  c.vector: void*
  c.map: void*

# Source directories or files, like the rest arguments in the command line
sources: [next]
Last updated on