The pcpp command

One command for every role: build, run, debug, start the editor, serve the language server and the debug adapter.

Calling pcpp

The command line is pcpp <source> [OPTIONS], or pcpp --clean [<folder>] [--dry-run] to clear an output folder (see Cleaning an output folder). With no arguments, or with -h / --help, pcpp prints its help (both usage forms, every option, examples) and exits 0. Every run starts with the banner (PaskalCPP™ CLI v<version>, the copyright line, https://paskalcpp.org); pcpp editor, --lsp and --dap print none.

• The source is the one argument that is not an option; options may come before or after it.
• The source's extension is always .pcpp: pcpp hello and pcpp hello.txt both build hello.pcpp.
• A source that does not exist is Error: Source file not found: <full path>, exit 2.
• Option names are exact case; a name pcpp does not know is Error: Unknown flag: <name>, followed by Run pcpp -h to see available options, exit 2.
• A second source is Error: Unexpected argument: <arg>; no source is Error: Source file is required. Both exit 2.

Options

• An option that takes a value, given none, is an error naming what it needs, exit 2.
• The compiler checks the -t and -opt values: one it does not take is CMP0001 (bad value '<value>' for option target), then Failed., exit 1.
• A retired level name (release_safe, release_fast, release_small) is not taken either: CMP0001 names its new one ('release_fast' is no longer a value of option optimize: write 'fast').
• A relative -o path is taken under the working folder; with no -o and no @outputpath the output folder is output there.
• -opt wins over the source's @optimize, as -t wins over @target. With --defaults (the editor passes it) each only stands in where the source has none.
• While zig builds, pcpp shows it is alive: on a console, or with --progress (the editor passes it), the Building <name>... line is redrawn in place with the seconds; on a pipe without --progress, a Building <name>... <n>s line appears every 10 seconds.

What a build prints

A build prints its steps: Compiling <source>, Target platform: <triple>, Optimize level: <level>, Subsystem: <kind> (Windows targets), Saving build file..., Building <name>..., then Build succeeded. and Output: <artifact>, or Build failed with exit code <n>. and the reports.

Running the program

Everything after -- belongs to the program, as written: pcpp reads nothing after it (-o and --lsp there are program arguments), and the program receives it split as the C runtime splits a command line (quotes group words, \" is a quote). paramcount() counts the arguments and paramstr(i) reads one, the same on both targets.

module exe cli_args;

var
  LI: int32;

begin
  println("count {}", paramcount());
  for LI := 1 to paramcount() do
    println("param {} {}", LI, paramstr(LI));
  end;
end.

count 0
[Heap] Allocs: 0, Frees: 0, Leaked: 0

• Under -r the program reads the keyboard of the console pcpp runs in. With a redirected stdin (pcpp prog.pcpp -r < input.txt) it reads that file itself and sees its end, on both targets; with --terminal <pipe> its terminal is the named pipe an editor listens on.
• -r on a dll or a lib is the warning CMP0002, and the build succeeds, exit 0.

Combinations pcpp refuses

Each is a usage error with the pcpp -h hint, exit 2, and nothing is built:

• -r with -d (-r and -d cannot be used together)
• -d with -opt (-d builds debug; -opt cannot be used with it)
• --host without -d, --terminal without -r
• -- without -r or -d

Debugging from the command line

pcpp <file> -d makes a debug build (whatever @optimize says) and debugs it in the console debugger. It debugs x86_64-windows-gnu only: another target is DB0012, exit 1.

An exe is debugged on its own, and a dll in the exe that loads it (--host <exe>). A lib cannot be debugged on its own (debug the program that links it); a dll without --host and an exe with one are errors, exit 2. The debugger itself is on The debugger.

Cleaning an output folder

pcpp --clean [<folder>] clears a pcpp output folder, the current folder when none is given. It builds nothing and reads no source.

pcpp --clean output --dry-run
pcpp --clean output

It removes only what a build wrote there that a build writes again:

• Before it lists anything it proves the folder is pcpp's: pcpp-output.json and build.zig are both there, both read cleanly and agree (the same output folder, the same project, sources in this folder's generated\). A check that fails is CMP0006 (refusing to clean <folder>: <reason>, the reason naming the check), then Nothing deleted., exit 1.
• It also refuses a drive root, a folder that holds the build's own source (the project's folder or one above it), a folder that is a link, and a target that is a link: a junction or symbolic link is never entered or deleted through.
• It then prints pcpp output folder <folder>. To delete: and each target that exists with its file count and size. With --dry-run it stops there: Dry run: nothing deleted., exit 0.
• Without --dry-run it asks Delete these <n>? [y/N]. Only y or Y deletes, after every check runs again, and prints Deleted <n>.; any other answer, an empty line or the end of input is Nothing deleted., exit 0. A target still present after the delete is reported, then Clean failed., exit 1.
• The question is for a person: a stdin that is not a console (a pipe, a file, NUL) is Error: --clean asks a person, and stdin is not a console: nothing deleted, exit 1. No option answers it.
• --clean with a build option, --dry-run without --clean, and a second folder are usage errors with the pcpp -h hint, exit 2, and nothing is deleted.

Exit codes

module exe cli_exit;

#include <cstdlib>

begin
  println("leaving");
  exit(3);
end.

leaving
[Heap] Allocs: 0, Frees: 0, Leaked: 0

The other modes

• pcpp editor [files] starts the PaskalCPP Editor (res\editor\editor.exe beside pcpp.exe) with the files given, and returns at once. See The editor.
• pcpp --lsp runs the language server and pcpp --dap the debug adapter on stdin / stdout. Each takes no other argument (Error: --lsp takes no other argument, exit 2), and a --lsp after -- is a program argument. See The language server and The debugger.