Command line tools

This section describes the usage the commandline tools installed with ppci.

Take for example the stm32f4 blinky project. To build this project, run ppci-build.py in the project folder:

$ cd examples/blinky
$ ppci-build

This command is used to construct build files.

Or specify the buildfile a the command line:

$ ppci-build -f examples/blinky/build.xml

Instead of relying on a build system, the c3 compiler can also be activated stand alone.

$ ppci-c3c --machine arm examples/snake/game.c3

ppci-c3c

C3 compiler.

Use this compiler to produce object files from c3 sources and c3 includes. C3 includes have the same format as c3 source files, but do not result in any code.

usage: ppci-c3c [-h] [--log log-level] [--report report-file]
                [--html-report html-report-file]
                [--text-report text-report-file] [--verbose] [--version]
                [--machine {arm,avr,example,mcs6500,microblaze,mips,msp430,or1k,riscv,stm8,x86_64,xtensa}]
                [--mtune option] [--output output-file] [-g] [-S] [--ir]
                [--wasm] [--pycode] [-O {0,1,2,s}] [-i include]
                source [source ...]
source

source file

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

--machine, -m

target architecture

--mtune <option>

architecture option

--output <output-file>, -o <output-file>

output file

-g

create debug information

-S

Do not assemble, but output assembly language

--ir

Output ppci ir-code, do not generate code

--wasm

Output WASM (WebAssembly)

--pycode

Output python code

-O {0,1,2,s}

optimize code

-i <include>, --include <include>

include file

ppci-build

Build utility.

Use this to execute build files.

usage: ppci-build [-h] [--log log-level] [--report report-file]
                  [--html-report html-report-file]
                  [--text-report text-report-file] [--verbose] [--version]
                  [-f build-file]
                  [target [target ...]]
target
-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

-f <build-file>, --buildfile <build-file>

use buildfile, otherwise build.xml is the default

ppci-asm

Assembler utility.
usage: ppci-asm [-h] [--log log-level] [--report report-file]
                [--html-report html-report-file]
                [--text-report text-report-file] [--verbose] [--version]
                [--machine {arm,avr,example,mcs6500,microblaze,mips,msp430,or1k,riscv,stm8,x86_64,xtensa}]
                [--mtune option] [--output output-file] [-g]
                sourcefile
sourcefile

the source file to assemble

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

--machine, -m

target architecture

--mtune <option>

architecture option

--output <output-file>, -o <output-file>

output file

-g, --debug

create debug information

ppci-ld

Linker.

Use the linker to combine several object files and a memory layout to produce another resulting object file with images.

usage: ppci-ld [-h] [--log log-level] [--report report-file]
               [--html-report html-report-file]
               [--text-report text-report-file] [--verbose] [--version]
               [--output output-file] [--layout layout-file] [-g]
               obj [obj ...]
obj

the object to link

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

--output <output-file>, -o <output-file>

output file

--layout <layout-file>, -L <layout-file>

memory layout

-g

retain debug information

ppci-objcopy

Objcopy utility to manipulate object files.
usage: ppci-objcopy [-h] [--log log-level] [--report report-file]
                    [--html-report html-report-file]
                    [--text-report text-report-file] [--verbose] [--version]
                    --segment SEGMENT [--output-format OUTPUT_FORMAT]
                    input output
input

input file

output

output file

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

--segment <segment>, -S <segment>

segment to copy

--output-format <output_format>, -O <output_format>

output file format

ppci-objdump

Objdump utility to display the contents of object files.
usage: ppci-objdump [-h] [--log log-level] [--report report-file]
                    [--html-report html-report-file]
                    [--text-report text-report-file] [--verbose] [--version]
                    [-d]
                    obj
obj

object file

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

-d, --disassemble

Disassemble contents

ppci-opt

Optimizer
usage: ppci-opt [-h] [--log log-level] [--report report-file]
                [--html-report html-report-file]
                [--text-report text-report-file] [--verbose] [--version]
                [-O O]
                input output
input

input file

output

output file

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

-O <o>

Optimization level

ppci-cc

C compiler.

Use this compiler to compile C source code to machine code for different computer architectures.

usage: ppci-cc [-h] [--log log-level] [--report report-file]
               [--html-report html-report-file]
               [--text-report text-report-file] [--verbose] [--version]
               [--machine {arm,avr,example,mcs6500,microblaze,mips,msp430,or1k,riscv,stm8,x86_64,xtensa}]
               [--mtune option] [--output output-file] [-g] [-S] [--ir]
               [--wasm] [--pycode] [-O {0,1,2,s}] [-I dir] [-D macro]
               [--include file] [--trigraphs] [--std {c89,c99}]
               [--super-verbose] [-E] [--ast] [-c]
               source [source ...]
source

source file

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

--machine, -m

target architecture

--mtune <option>

architecture option

--output <output-file>, -o <output-file>

output file

-g

create debug information

-S

Do not assemble, but output assembly language

--ir

Output ppci ir-code, do not generate code

--wasm

Output WASM (WebAssembly)

--pycode

Output python code

-O {0,1,2,s}

optimize code

-I <dir>

Add directory to the include path

-D <macro>, --define <macro>

Define a macro

--include <file>

Include a file before all other sources

--trigraphs

Enable trigraph processing

--std {c89,c99}

The C version you want to use

--super-verbose

Add extra verbose output during C compilation

-E

Stop after preprocessing

--ast

Stop parsing and output the C abstract syntax tree (ast)

-c

Compile, but do not link

ppci-pascal

Pascal compiler.

Compile pascal programs.

usage: ppci-pascal [-h] [--log log-level] [--report report-file]
                   [--html-report html-report-file]
                   [--text-report text-report-file] [--verbose] [--version]
                   [--machine {arm,avr,example,mcs6500,microblaze,mips,msp430,or1k,riscv,stm8,x86_64,xtensa}]
                   [--mtune option] [--output output-file] [-g] [-S] [--ir]
                   [--wasm] [--pycode] [-O {0,1,2,s}]
                   source [source ...]
source

source file

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

--machine, -m

target architecture

--mtune <option>

architecture option

--output <output-file>, -o <output-file>

output file

-g

create debug information

-S

Do not assemble, but output assembly language

--ir

Output ppci ir-code, do not generate code

--wasm

Output WASM (WebAssembly)

--pycode

Output python code

-O {0,1,2,s}

optimize code

ppci-pycompile

Compile python code statically
usage: ppci-pycompile [-h] [--log log-level] [--report report-file]
                      [--html-report html-report-file]
                      [--text-report text-report-file] [--verbose] [--version]
                      [--machine {arm,avr,example,mcs6500,microblaze,mips,msp430,or1k,riscv,stm8,x86_64,xtensa}]
                      [--mtune option] [--output output-file] [-g] [-S] [--ir]
                      [--wasm] [--pycode] [-O {0,1,2,s}]
                      source [source ...]
source

source file

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

--machine, -m

target architecture

--mtune <option>

architecture option

--output <output-file>, -o <output-file>

output file

-g

create debug information

-S

Do not assemble, but output assembly language

--ir

Output ppci ir-code, do not generate code

--wasm

Output WASM (WebAssembly)

--pycode

Output python code

-O {0,1,2,s}

optimize code

ppci-readelf

Clone of the famous readelf utility
usage: ppci-readelf [-h] [--log log-level] [--report report-file]
                    [--html-report html-report-file]
                    [--text-report text-report-file] [--verbose] [--version]
                    [-a] [--file-header] [-l] [-S] [-s] [-e] [-x HEX_DUMP]
                    [--debug-dump {rawline,}]
                    elf
elf

ELF file

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

-a, --all

Equivalent to: -h -l -S -s -r -d -V -A -I

--file-header

Display the ELF file header

-l, --program-headers

Display the program headers

-S, --section-headers

Display the section headers

-s, --syms

Display the symbol table

-e, --headers

Equivalent to: –file-header -l -S

-x <hex_dump>, --hex-dump <hex_dump>

Dump contents of section as bytes

--debug-dump {rawline,}

Display contents of dwarf sections

ppci-wasmcompile

Static web assembly compiler.

This command line tool takes web assembly to native code.

usage: ppci-wasmcompile [-h] [--log log-level] [--report report-file]
                        [--html-report html-report-file]
                        [--text-report text-report-file] [--verbose]
                        [--version]
                        [--machine {arm,avr,example,mcs6500,microblaze,mips,msp430,or1k,riscv,stm8,x86_64,xtensa}]
                        [--mtune option] [--output output-file] [-g] [-S]
                        [--ir] [--wasm] [--pycode] [-O {0,1,2,s}]
                        wasm file
wasm file

wasm file to compile

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

--machine, -m

target architecture

--mtune <option>

architecture option

--output <output-file>, -o <output-file>

output file

-g

create debug information

-S

Do not assemble, but output assembly language

--ir

Output ppci ir-code, do not generate code

--wasm

Output WASM (WebAssembly)

--pycode

Output python code

-O {0,1,2,s}

optimize code

ppci-yacc

Parser generator utility.

This script can generate a python script from a grammar description.

Invoke the script on a grammar specification file:

$ ppci-yacc test.x -o test_parser.py

And use the generated parser by deriving a user class:

import test_parser
class MyParser(test_parser.Parser):
    pass
p = MyParser()
p.parse()

Alternatively you can load the parser on the fly:

import yacc
parser_mod = yacc.load_as_module('mygrammar.x')
class MyParser(parser_mod.Parser):
    pass
p = MyParser()
p.parse()
usage: ppci-yacc [-h] [--log log-level] [--report report-file]
                 [--html-report html-report-file]
                 [--text-report text-report-file] [--verbose] [--version] -o
                 OUTPUT
                 source
source

the parser specification

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

-o <output>, --output <output>

ppci-wasm2wat

Convert binary wasm to wasm text (WAT) format.
usage: ppci-wasm2wat [-h] [--log log-level] [--report report-file]
                     [--html-report html-report-file]
                     [--text-report text-report-file] [--verbose] [--version]
                     [-o wat file]
                     wasm file
wasm file

wasm file to read

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

-o <wat file>, --output <wat file>

File to write the WAT file to, default is stdout

ppci-wat2wasm

Convert binary wasm to wasm text (WAT) format.
usage: ppci-wat2wasm [-h] [--log log-level] [--report report-file]
                     [--html-report html-report-file]
                     [--text-report text-report-file] [--verbose] [--version]
                     [-o wasm file]
                     wat file
wat file

wasm text file to read

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

-o <wasm file>, --output <wasm file>

File to write the binary wasm file to, default is stdout

ppci-wabt

Wasm binary toolkit (WABT)
usage: ppci-wabt [-h] [--log log-level] [--report report-file]
                 [--html-report html-report-file]
                 [--text-report text-report-file] [--verbose] [--version]
                 {wat2wasm,wasm2wat,show_interface} ...
-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit

ppci-wabt show_interface

usage: ppci-wabt show_interface [-h] wasm file
wasm file

wasm file to read

-h, --help

show this help message and exit

ppci-wabt wasm2wat

usage: ppci-wabt wasm2wat [-h] [-o wat file] wasm file
wasm file

wasm file to read

-h, --help

show this help message and exit

-o <wat file>, --output <wat file>

File to write the WAT file to, default is stdout

ppci-wabt wat2wasm

usage: ppci-wabt wat2wasm [-h] [-o wasm file] wat file
wat file

wasm text file to read

-h, --help

show this help message and exit

-o <wasm file>, --output <wasm file>

File to write the binary wasm file to, default is stdout

ppci-hexutil

hexfile manipulation tool by Windel Bouwman

usage: ppci-hexutil [-h] {info,new,merge} ...
-h, --help

show this help message and exit

ppci-hexutil info

usage: ppci-hexutil info [-h] hexfile
hexfile
-h, --help

show this help message and exit

ppci-hexutil merge

usage: ppci-hexutil merge [-h] hexfile1 hexfile2 rhexfile
hexfile1

hexfile 1

hexfile2

hexfile 2

rhexfile

resulting hexfile

-h, --help

show this help message and exit

ppci-hexutil new

usage: ppci-hexutil new [-h] hexfile address datafile
hexfile
address

hex address of the data

datafile

binary file to add

-h, --help

show this help message and exit

ppci-hexdump

Display file contents in hexadecimal
usage: ppci-hexdump [-h] [--log log-level] [--report report-file]
                    [--html-report html-report-file]
                    [--text-report text-report-file] [--verbose] [--version]
                    file
file

File to dump contents of

-h, --help

show this help message and exit

--log <log-level>

Log level (info,debug,warn)

--report

Specify a file to write the compile report to

--html-report

Write html report file

--text-report

Write a report into a text file

--verbose, -v

Increase verbosity of the output

--version, -V

Display version and exit