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
.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
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(51864a35de7890d63bfd8acecdb62d20372ca963) built at 2024/09/27T22:58:21+0800 by go1.23.0
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
-F
-F
represents the custom formatter for generated code. Example:
next -F "go=gofmt -s -w" \
-F "ts=prettier --write" \
-F "cpp=clang-format -i" \
...
-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 ...
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 commands for code generation. Annotation solvers are executed in a separate process to solve annotations. All annotations are passed to the solver command 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" ...
In the example above, the message-type-allocator
is a custom annotation solver command that reads the message types from the message-types.json
file and rewrite the message types to the message-types.json
file.
-grammar
-grammar
represents the custom grammar for the next source code.
Example:
next -grammar grammar.yaml ...
next -grammar grammar.json ...
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 YAML or 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." ...
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. The trace message is used for debugging the compiler itself. Verbosity 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:
# This is a next project file.
# Verbose level, like the -v flag
# 0: quiet, 1: debug, 2: trace
verbose: 1
# Header comment, like the -head flag. By default, it is 'Code generated by "next ${VERSION}"; DO NOT EDIT'
head: 'Code generated by "next"; DO NOT EDIT'
# Enable the strict mode, like the -s flag
strict: true
# Grammar file, like the -grammar flag
grammar: grammar.yaml
# Variables, like the -D flag
env:
PROJECT_NAME: demo
GO_MOD: github.com/mkideal/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
# Formatter for target languages, like the -F flag
#formatter:
# go: gofmt -s -w
# cpp: clang-format -i
# c: clang-format -i
# java: java -jar /path/to/google-java-format-1.24.0-all-deps.jar -i
# 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]
.Perm
.Perm
represents the file permission for generated code if {{head}}
is called.
.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.
.formatter
.formatter
represents the custom formatter for generated code.
Example:
formatter:
go: gofmt -s -w
ts: prettier --write
java: java -jar /path/to/google-java-format-1.24.0-all-deps.jar -i
cpp: clang-format -i
.grammar
.grammar
represents the custom grammar for the next source code.
Example:
grammar: grammar.yaml
See the -grammar 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 commands 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.