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]
                [--pudb]
                [--machine {arm,avr,example,m68k,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}] [--instrument-functions]
                [-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

--pudb

Drop into post mortem pudb session on crash

--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

--instrument-functions

Instrument given functions

-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]
                  [--pudb] [-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

--pudb

Drop into post mortem pudb session on crash

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

use buildfile, otherwise build.xml is the default

ppci-archive

Archive manager.

Create or update an archive. Or extract object files from the archive.

usage: ppci-archive [-h] [--log log-level] [--report report-file]
                    [--html-report html-report-file]
                    [--text-report text-report-file] [--verbose] [--version]
                    [--pudb]
                    {create,display} ...
-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

--pudb

Drop into post mortem pudb session on crash

ppci-archive create

usage: ppci-archive create [-h] archive [obj [obj ...]]
archive

Archive filename.

obj

the object to link

-h, --help

show this help message and exit

ppci-archive display

usage: ppci-archive display [-h] archive
archive

Archive filename.

-h, --help

show this help message and exit

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]
                [--pudb]
                [--machine {arm,avr,example,m68k,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

--pudb

Drop into post mortem pudb session on crash

--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]
               [--pudb] [--output output-file] [--library library-filename]
               [--layout layout-file] [-g] [--relocatable] [--entry ENTRY]
               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

--pudb

Drop into post mortem pudb session on crash

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

output file

--library <library-filename>

Add library to use when searching for symbols.

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

memory layout

-g

retain debug information

--relocatable, -r

Generate relocatable output

--entry <entry>, -e <entry>

Use entry as the starting symbol of execution of the program.

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]
                    [--pudb] [--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

--pudb

Drop into post mortem pudb session on crash

--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]
                    [--pudb] [-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

--pudb

Drop into post mortem pudb session on crash

-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]
                [--pudb] [-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

--pudb

Drop into post mortem pudb session on crash

-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]
               [--pudb]
               [--machine {arm,avr,example,m68k,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}] [--instrument-functions]
               [-I dir] [-D macro] [-U macro] [--include file] [--trigraphs]
               [--std {c89,c99}] [--super-verbose] [--freestanding] [-E] [-M]
               [--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

--pudb

Drop into post mortem pudb session on crash

--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

--instrument-functions

Instrument given functions

-I <dir>

Add directory to the include path

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

Define a macro

-U <macro>, --undefine <macro>

Undefine 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

--freestanding

Compile in free standing mode.

-E

Stop after preprocessing

-M

Instead of preprocessing, emit a makefile rule with dependencies

--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]
                   [--pudb]
                   [--machine {arm,avr,example,m68k,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}] [--instrument-functions]
                   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

--pudb

Drop into post mortem pudb session on crash

--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

--instrument-functions

Instrument given functions

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]
                      [--pudb]
                      [--machine {arm,avr,example,m68k,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}]
                      [--instrument-functions]
                      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

--pudb

Drop into post mortem pudb session on crash

--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

--instrument-functions

Instrument given functions

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]
                    [--pudb] [-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

--pudb

Drop into post mortem pudb session on crash

-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] [--pudb]
                        [--machine {arm,avr,example,m68k,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}]
                        [--instrument-functions]
                        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

--pudb

Drop into post mortem pudb session on crash

--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

--instrument-functions

Instrument given functions

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]
                 [--pudb] -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

--pudb

Drop into post mortem pudb session on crash

-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]
                     [--pudb] [-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

--pudb

Drop into post mortem pudb session on crash

-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]
                     [--pudb] [-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

--pudb

Drop into post mortem pudb session on crash

-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]
                 [--pudb]
                 {wat2wasm,wasm2wat,show_interface,run} ...
-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

--pudb

Drop into post mortem pudb session on crash

ppci-wabt run

usage: ppci-wabt run [-h] [--arg arg] [--target target]
                     [--function function_name]
                     wasm file
wasm file

wasm file to read

-h, --help

show this help message and exit

--arg <arg>

Argument to wasm function

--target {native,python}

Which target to generate code for

--function <function_name>, -f <function_name>

Function to run

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-ocaml

OCaml utility.

Multiple usage possible, for example:

usage: ppci-ocaml [-h] [--log log-level] [--report report-file]
                  [--html-report html-report-file]
                  [--text-report text-report-file] [--verbose] [--version]
                  [--pudb]
                  {disassemble,opt} ...
-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

--pudb

Drop into post mortem pudb session on crash

ppci-ocaml disassemble

usage: ppci-ocaml disassemble [-h] bytecode-file
bytecode-file

OCaml bytecode file to disassemble

-h, --help

show this help message and exit

ppci-ocaml opt

usage: ppci-ocaml opt [-h]
                      [--machine {arm,avr,example,m68k,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}]
                      [--instrument-functions]
                      bytecode-file
bytecode-file

OCaml bytecode file to disassemble

-h, --help

show this help message 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

--instrument-functions

Instrument given functions

ppci-java

Java handling utility.
usage: ppci-java [-h] [--log log-level] [--report report-file]
                 [--html-report html-report-file]
                 [--text-report text-report-file] [--verbose] [--version]
                 [--pudb]
                 {compile,javap,jar} ...
-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

--pudb

Drop into post mortem pudb session on crash

ppci-java compile

usage: ppci-java compile [-h] [--output output-file] [-g] [-S] [--ir] [--wasm]
                         [--pycode] [-O {0,1,2,s}] [--instrument-functions]
                         [--machine {arm,avr,example,m68k,mcs6500,microblaze,mips,msp430,or1k,riscv,stm8,x86_64,xtensa}]
                         [--mtune option]
                         java class file
java class file

class file to compile

-h, --help

show this help message and exit

--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

--instrument-functions

Instrument given functions

--machine, -m

target architecture

--mtune <option>

architecture option

ppci-java jar

usage: ppci-java jar [-h] java jar file
java jar file

jar file to inspect

-h, --help

show this help message and exit

ppci-java javap

usage: ppci-java javap [-h] java class file
java class file

class file to inspect

-h, --help

show this help message and exit

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]
                    [--pudb] [--width WIDTH]
                    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

--pudb

Drop into post mortem pudb session on crash

--width <width>

Width of the hexdump.