` directory.
#### Release / debug variants
Release and debug builds are also profile variants. When a project has more than one platform, name profiles by the whole output flavour instead of separating platform and optimization settings into targets:
```make
profiles {
win64_debug {
TARGET_PLATFORM = "win64"
C_FLAGS += ["/Od", "/Zi"]
}
win64_release {
TARGET_PLATFORM = "win64"
C_FLAGS += ["/O2"]
}
unix_debug {
TARGET_PLATFORM = "unix"
C_FLAGS += ["-O0", "-g"]
}
unix_release {
TARGET_PLATFORM = "unix"
C_FLAGS += ["-O2"]
}
}
```
Select a profile on the command line, for example `nobs win64_debug` or `nobs unix_release`.
---
### Building a simple binary
```make
mybinary:
{
CPP_FILES=P"(main.cpp)"
}
```
---
### Building a static library
Use `STATIC` to select the static-library builder explicitly. Keep compilation in a separate target that produces `OBJS`, then merge those objects into the library target with `+core`.
```make
mylib: +core +api
{
STATIC
OBJS
OUTPUT_NAME="mylib.lib"
^INCLUDE
}
api:
{
NO_TOOL
^INCLUDE = P"(.)"
}
core:
{
C_FILES=[P"(mylib.c)", P"(util.c)"]
C_FLAGS=["/c"]
}
```
For GNU, use the same shape with `OUTPUT_NAME="libmylib.a"` and `C_FLAGS=["-c"]`.
**Resulting output context:**
```make
{
LIB=P"(/path/to/mylib.lib)"
INCLUDE=P"(/path/to/nobs_txt/.)"
}
```
In the above example `STATIC` selects `lib.exe` on MSVC or `ar` on GNU, and `OUTPUT_NAME` names the archive. `OBJS` is declared in `mylib` so the builder can be selected before dependencies are built. `core` then produces the actual `OBJS`, which are added to `mylib` because of the `+` modifier on `core`. The library builder emits `LIB`, and `^INCLUDE` exports the public include path from `api`.
### Building a DLL
You can build a DLL like this:
```make
dll: +core api
{
DLL
OUTPUT_NAME="mydll.dll"
OBJS
LIB = "kernel32.lib"
DEF = P"(mylib.def)"
^API=api.INCLUDE
}
api:
{
NO_TOOL
^INCLUDE=P"(api)"
}
core:
{
C_FILES=[
P"(dllmain.c)",
P"(functions.c)"
]
C_FLAGS= ["/c"]
INCLUDE=P"(include)"
}
```
Note the output of `core` is `OBJS`, because that is the behaviour of the `cl.exe` tool when `/c` is present (see MSVS toolchain / Available tools / cl.exe). The `dll` target declares `OBJS` so the linker builder can be selected before dependencies are built. `core` is referenced with a `+` modifier, which means the actual `OBJS` produced by `core` are moved straight into the `dll` context and used in the linking process.
The `api` target declares `NO_TOOL` because it is metadata-only; it exports include paths but does not compile or link anything. When the MSVC linker produces an import library next to the DLL, the DLL target output also includes `LIB` pointing to that import library, so dependent targets can link against it through the usual `LIB` variable.
---
### Value lookups
Something very useful for embedded are value lookups.
```make
fw: cpu
{
CPU = "CM0PLUS"
C_FLAGS = cpu.gcc_flags[CPU]
C_FILES = P"(main.c)"
}
cpu:
{
NO_TOOL
^gcc_flags =
{
CM0PLUS=["-mthumb", "-mcpu=cortex-m0plus"]
CM3=["-mthumb", "-mcpu=cortex-m3"]
}
}
```
After cpu target is built, it exposes gcc_flags in its output. The `cpu` target declares `NO_TOOL` because it is only a lookup table and should not select a compiler. The output is then added to fw as new context variable under the name 'cpu'. Contexts can be either accessed with dotted notation or it can be indexed with [], which is the same but the inside of [] is resolved beforehand. In the example above the access resolves to cpu.gcc_flags.CM0PLUS. The content of that variable is used for compiling main.c.
---
### Subdirectories / multiple modules
In order to connect multiple nobs.txt files you need to use .nobs_project.txt. This file can be created automatically with nobs --create-project ran in root directory of your project. To avoid typing out paths, first create modules' directories and their nobs files and then run nobs --create-project. Once project file exists you can start using qualified target names for dependencies. E.g. take a structure like this:
myapp_proj
│─── .nobs_project.txt
│
├─── myapp
│ ├── main.c
│ ├── nobs.txt
│ │
│ └── include
│ └── globals.h
│
├─── mylib
│ ├── func.c
│ ├── nobs.txt
│ │
│ └── include
│ └── mylib.h
│
└─── common
├── nobs.txt
│
└── include
└── common.h
This project builds a static library and an application that uses it. It also has a shared _common_ unit that exposes include paths used by both modules. Targets from _mylib_ and _common_ are referenced using the qualified notation `unit::target`. Aside from that, working with these targets is no different from using local targets in their short form.
```make
unit myapp
build: mylib::api common::include +mylib::build
{
OUTPUT_NAME="myapp.exe"
INCLUDE = [
P"(include)",
mylib.api.INCLUDE,
common.include.INCLUDE
]
C_FILES=P"(main.c)"
}
```
The build of the lib could look like:
```make
unit mylib
build: common::include +core
{
STATIC
OBJS
OUTPUT_NAME="mylib.lib"
INCLUDE = common.include.INCLUDE
}
api:
{
NO_TOOL
^INCLUDE=P"(include)"
}
core:
{
C_FILES=P"(func.c)"
C_FLAGS=["/c"]
}
```
The shared common unit only exports include paths:
```make
unit common
include:
{
NO_TOOL
^INCLUDE=P"(include)"
}
```
The project file generated with nobs --create-project should look like:
```
name nobs_proj
units
{
myapp {
"myapp\nobs.txt"
}
mylib {
"mylib\nobs.txt"
}
common {
"common\nobs.txt"
}
}
```
Running nobs at root directory will try to build the main target of the main unit, which equals to first target of first unit. That means nobs will start at myapp::build. `common::include` exposes a shared `INCLUDE` variable, available as `common.include.INCLUDE` in dependent targets. `mylib::build` uses `STATIC` to select the static-library builder and declares `OBJS` so it can be selected before `core` is built; `core` then supplies the actual object files through the `+core` dependency. When `mylib::build` is done it will have a `LIB` variable pointing to where the library was built in its output context (See MSVS toolchain / Available tools / lib.exe). Because there is a `+` on `mylib::build` in the app target, this variable will be moved straight into `myapp::build` where in turn it will be used in the linking step (See MSVS toolchain / Available tools / cl.exe).
### External libraries
There isn't much special about libraries being 3d party from using your own built libraries. To use a library in linking you need to use LIB variable in a context that is either built by cl.exe, link.exe, gcc or g++. For instance:
```
myapp:
{
C_FILES=P"(main.c)"
LIB=["kernel32.lib", "advapi32.lib"]
}
```
This will produce a build line like this:
`cl.exe "E:\long path\to\myapp\main.c" "kernel32.lib" "advapi32.lib"`
---
Command-line interface
----------------------
`nobs` is controlled primarily through the command line.
A build is defined by selecting an optional target, an optional project profile, and optional context variables as assignments.
### Basic usage
`nobs [options] [target] [profile] [assignment]*`
Non-option arguments are evaluated one by one:
* `target`
Optional target name to build.
If omitted, Nobs builds the main target of the main unit. The main unit is the first unit in `.nobs_project.txt`; the main target is the first target in that unit.
Qualified target names such as `unit::target` or `project/unit::target` can be used when a project file is active.
* `profile`
Optional name of a profile from `.nobs_project.txt`.
If a `default` profile exists, it is applied automatically. A selected profile is applied after `default`.
Only one explicit profile can be selected.
* `assignment`
Zero or more variable assignments passed on the command line.
These assignments are injected into the implicit context and behave the same way as assignments in a nobs file.
The order of `target`, `profile`, and assignments is flexible, but only one target and one explicit profile can be specified. If a token matches a target name, it is treated as the target before profile lookup is attempted.
The implicit context is then assembled as host variables, `default` profile, selected profile, and command-line assignments. Command-line assignments are applied last, so they can override or extend profile values.
Example:
`nobs app debug USE_UNICODE DEFAULT_LANG=en`
* * *
### Options
#### `--help`
Displays a short help message describing available options and usage.
`nobs --help`
* * *
#### `-l` — list targets
Lists all targets defined in the selected unit. The unit argument is required.
`nobs -l `
Use `1` as an alias for the main unit, which is the first unit listed in `.nobs_project.txt`:
`nobs -l 1`
When a unit is defined by multiple files, targets from all of those files are listed. Imported project units are not included. Without a project file, `1` selects the unit from the default `nobs.txt` file or the standalone file selected with `-f`. The main target of the selected unit is highlighted in green when output is written to a terminal.
This can be useful for CI/CD integrations. You can list targets, then insert steps into pipeline based on the list.
This option does not perform any build.
* * *
#### `-u` — list units
Lists all units defined in the project file.
`nobs -u`
This is useful for inspecting project structure and available build modules. The output is an inventory of known units, not a contract for default build order. Use `nobs -l` from the project root to confirm which targets belong to the project main unit.
* * *
#### `-p` — list profiles
Lists all profiles defined in the project file.
`nobs -p`
This option does not perform any build.
* * *
#### `-j ` — thread count
Sets the maximum number of parallel jobs.
`nobs -j 8`
If `-j` is used without a number, Nobs uses the hardware concurrency reported by the host system. Values below `1` are clamped to `1`.
* * *
#### `-v ` — verbosity level
Sets the verbosity level.
`nobs -v 3`
* Default verbosity level is `5` (`Info`).
* `-v` without a number sets verbosity to `3` (`Verbose`).
* Lower values produce more detailed output.
* Higher values reduce console noise.
* * *
#### `-d` — dump implicit context
Prints the raw implicit context before the build starts.
`nobs -d app debug`
This is useful when checking which host variables, default profile variables, selected profile variables, and command-line assignments are copied toward targets. Conditional blocks in the implicit context are not evaluated by this dump; they are evaluated later in each target context. Use verbose output (`-v` or `-v 3`) when you need to inspect the evaluated target input context used by the selected builder.
* * *
#### `-f ` — nobs file override
Overrides the default nobs file.
`nobs -f custom.nobs`
The file path can be absolute or relative to the directory where `nobs` is launched. When `-f` is used, Nobs runs that file as a standalone entry file and does not load a project file discovered from the current directory.
* * *
#### `-o ` — main target output
Writes the main target output context to a text file. This can be useful for CI/CD integrations that need to read artifact paths produced by the build.
`nobs app -o build-output.txt`
This option does not set the built artifact name. Use `OUTPUT_NAME` for that.
* * *
#### `-r` — register current project
Registers the current project in the user registry.
`nobs -r`
This option does not perform a build.
* * *
#### `--find-compilers`
Detects available default toolchains and writes them to the machine-local `.nobs_registry.txt`.
`nobs --find-compilers`
Run this when setting up a machine or after installing a new compiler/toolchain that Nobs should discover automatically.
* * *
#### `--version`
Prints the current version of `nobs`.
`nobs --version`
* * *
#### `--create-project`
Initializes a new `.nobs_project.txt` file in the current directory.
`nobs --create-project`
Run this after creating module directories and their `nobs.txt` files. Nobs scans the current directory tree and creates the `units` section from `nobs.txt` files whose first line declares `unit `. Files without a unit declaration are skipped.
* * *
#### Command-line assignments
Assignments passed on the command line behave the same as assignments defined in a nobs file.
`nobs app release msvc 'VERSION="1.0"'`
These assignments are merged into the implicit context so they can influence registered tool selection, builder choice, and target behavior.
Each assignment must be passed as one command-line argument. Quote the whole assignment when the value contains spaces or list syntax, for example:
`nobs app 'C_FLAGS+=["/Od", "/Zi"]'`
**Quotes must survive the shell.** Nobs parses the argument exactly as it receives it from the operating system. In many shells, writing `VERSION="1.0"` removes the quotes before Nobs sees the argument, so Nobs receives `VERSION=1.0`. Quote or escape the whole assignment in a shell-specific way, for example `'VERSION="1.0"'` in PowerShell or POSIX shells.
**Bare identifiers are converted to strings on the command line.** `VERSION=release` is parsed as `VERSION="release"`. In a `nobs.txt` file, `release` would be an identifier reference, but command-line identifiers are converted to strings because command lines and CI/CD systems often remove quotes and identifier references are rarely useful there.
**Numbers stay numbers unless quoted.** `VERSION=1` is parsed as an integer number, while `VERSION="1"` is parsed as a string. `1.0` is not a valid Nobs number literal because decimal numbers are not part of the assignment syntax. Use a string for version-like values: `VERSION="1.0"`.
---