Builder (hcbuild)

Project build system that reads .prj configuration files and orchestrates compilation, assembly, and linking in one command. The project file path is used as the base directory for all relative source file paths.

Command Line

hcbuild [options] <project.prj> <command> [config]

Argument	Description
`<project.prj>`	Path to the project configuration file (required)
`<command>`	`make` to build, `clean` to remove output files (required)
`[config]`	Link configuration name. Default: `release`. Allows multiple `[link:NAME]` sections.

Command-Line Options

Option	Description
`--sdk-path <dir>`	Base directory for all tools (compiler, assembler, linker, librarian). Overrides `HC_SDK_PATH` and `sdk_path` in `[config]`.
`--asm-path <dir>`	Assembler directory (defaults to `sdk_path`).
`--link-path <dir>`	Linker directory (defaults to `sdk_path`).
`--lib-path <dir>`	Librarian directory (defaults to `sdk_path`).
`--output-dir <dir>`	Output directory for all generated files. Overrides `HC_OUTPUT_DIR` and `output_dir` in `[config]`.
`-I <dir>`	Add include path (for B language `#include`). Repeatable.
`--verbose, -v`	Print each tool invocation before executing.
`--dump`	Generate `.dump` assembly listing files alongside `.obj` files.
`--keep`	Keep intermediate `.__s` files (normally deleted after assembly).
`--help, -h`	Show help message.

Environment Variables

Variable	Description
`HC_SDK_PATH`	Base directory for all tools. Overridden by `--sdk-path`.
`HC_OUTPUT_DIR`	Output directory. Overridden by `--output-dir`.

Build Order

When make is executed, hcbuild processes the project in this order:

Collect objects from [lib:start] and [libs:start] (linked first)
Compile and assemble source files from all [files:*] sections
Collect objects from [lib] and [libs] (linked after user objects)
Invoke the linker with all collected objects

.prj File Format — Complete Reference

The project file uses an INI-like syntax. Lines starting with ; or # are comments. Section headers use square brackets. Keys can have values after =, or stand alone (no = needed for source file entries). Values may be quoted with double quotes.

1. [config] — Global Settings

Optional section. All keys are optional.

Key	Values	Description
`sdk_path`	Path string	Base directory where `hcbcomp-`, `hcasm-`, `hclink-*`, and `hclib` are located.
`output_dir`	Path string	Directory for all output files. If not set, output goes next to the `.prj` file.
`verbose`	`yes`, `true`, `1`, `enable`	Print each tool command before executing.
`dump`	`yes`, `true`, `1`, `enable`	Generate `.dump` assembly listing files.
`keep`	`yes`, `true`, `1`, `enable`	Keep intermediate `.__s` files after assembly.

[config]
sdk_path = ../../bin
verbose = yes
keep = true

2. [files:ARCH] — Source Files

Lists source files for a specific target architecture. Each line is a filename (no = value). The architecture determines which compiler and assembler are used. Multiple [files:ARCH] sections can coexist in one project.

Architecture	Compiler	Assembler	Use Case
`z80`	`hcbcomp-z80`	`hcasm-z80`	Z80 / CP/M, MSX-DOS
`8086`	`hcbcomp-8086`	`hcasm-8086`	8086 / MS-DOS COM (near pointers)
`8086exe`	`hcbcomp-8086exe`	`hcasm-8086`	8086 / MS-DOS EXE (far pointers, MZ format)
`8080`	`hcbcomp-8080`	`hcasm-8080`	8080 / CP/M
`8085`	`hcbcomp-8085`	`hcasm-8085`	8085 / CP/M

Supported Source File Extensions

Extension	Step 1	Step 2	Notes
`.b`, `.B`	Compile to `.__s`	Assemble to `.obj`	B language source. Uses `hcbcomp-ARCH`.
`.s`, `.S`	—	Assemble to `.obj`	Assembly source. Uses `hcasm-ARCH`.
`.obj`	Passed directly to linker		Pre-compiled object file.

[files:z80]
main.b
utils.s
startup.obj

[files:8086]
portable.b

3. [libs] and [lib] — Library Files

Lists library (.lib) and object (.obj) files to link. [libs] and [lib] are equivalent — both are linked after all source files have been compiled and assembled.

[libs]
../../libs/z80-cpm-b.lib
extra/mylib.lib

4. [libs:start] and [lib:start] — Startup Objects

Libraries and objects linked before user source files. Use this for startup code (_start). The linker ensures the object containing _start is placed first.

[libs:start]
start.obj
crt.lib

5. [link:NAME] — Link Configuration

Defines how to produce the final executable. NAME is the configuration name (e.g., release, debug). Pass the name as the third argument to hcbuild. If only one [link:*] section exists, it is used regardless of name.

Key	Default	Description
`format`	`bin`	Output format. `bin` = flat binary (COM/ROM), `mz` = MZ EXE (MS-DOS segmented), `rex` = REX relocatable, `lib` = librarian output (produces `.lib` using hclib).
`filename`	`a.out`	Output file name. Relative paths are resolved from the `output_dir` or project directory.
`text`	(none)	Text section start address (hex or decimal). Typical CP/M .COM: `0x100`. ROM images may use `0x0000` or `0x4000`.
`data`	(none)	Data section start address. If omitted, data follows immediately after text.
`bss`	(none)	BSS section start address. If omitted, BSS follows immediately after data.
`align`	(none)	Section alignment in bytes. Ensures each section starts at a multiple of this value.
`stack`	4096	Stack size in bytes. Only meaningful for `format = mz`. The stack is placed at the end of the BSS section.
`symbols`	(none)	If set, generates a symbol table file listing all labels with addresses. Format: `$ADDR NAME [TYPE file.obj]`.

; CP/M .COM target
[link:release]
format = bin
text = 0x100
filename = program.com
symbols = program.sym

; MS-DOS .EXE target
[link:msdos]
format = mz
stack = 1024
filename = program.exe

; ROM image target
[link:rom]
format = bin
text = 0x4000
bss = 0xC000
filename = firmware.bin

6. [blang:include_path] — B Compiler Include Paths

Additional include directories passed to the B compiler via -I. Each line is a path. These paths are used for #include resolution in .b source files.

[blang:include_path]
../include
../lib/common

Complete Example

A multi-target project building for both Z80/CP/M and 8086/MS-DOS EXE:

; game.prj — Retro game for Z80 CP/M and 8086 MS-DOS
[config]
sdk_path = ../../bin
verbose = yes

[files:z80]
main.b
sound.b
gfx.b
cp/m_wrapper.s

[files:8086exe]
main.b
sound.b
gfx.b
dos_wrapper.s

[libs]
../../libs/z80-cpm-b.lib

[libs:start]
startup.obj

[link:cpm]
format = bin
text = 0x100
filename = GAME.COM

[link:dos]
format = mz
stack = 4096
filename = GAME.EXE

Build commands:

hcbuild game.prj make cpm      # build CP/M version
hcbuild game.prj make dos      # build MS-DOS EXE version
hcbuild game.prj clean         # remove all outputs

[Quick Start] · [Linker] · [B Compiler]