The development setup revolves around the MCU directories. This is where the make commands must be executed. make all will produce a number of build artifacts in the build/ subdirectory (excluded from git), including the hex, bin and elf files containing AmForth compiled for given target. make or make help shows the available targets for given MCU. To build a different target than the default one, run make all with TARGET environment variable set accordingly, e.g. TARGET=XXX make all.

The build process produces following files in the build/ directory:

Binary Files

  • amforth.bin - binary file for uploads into physical board
  • amforth.hex - Intel hex file for uploads into physical board
  • amforth.elf - executable for emulation

Build Files

  • amforth.dep - list of files used in the build
  • amforth.map - linker map of the executable
  • amforth.sym - list of all symbols of the executable
  • amforth.lst - assembler listing from the linker
  • amforth.lst-as - assembler listing from the assembler
  • amforth.sal - symbol and source line listing (debug info)

Documentation Files

  • amforth.html - reference card of all words in this build
  • amforth.txt - reference card of all words in this build
  • amforth.toc - list of headers of all words in this build

Toolchain

The toolchain is generally the standard GNU assembler/linker/debugger suite tailored for given embedded architecture. For ARM it is the arm-none-eabi variant, and for RISC-V it is the riscv-none-elf variant. The toolchain can be installed in many different ways. Variables TC_DIR and CROSS allow connecting the AmForth build system to a pre-installed toolchain.

For example if you are using Arduino IDE for some development on a given board, you can point TC_DIR at the location where Arduino IDE installed this toolchain. The CROSS variable defines the common prefix that the toolchain binaries use, e.g. arm-none-eabi- when the assembler binary is named arm-none-eabi-as.

Command make toolchain is a convenient way to install the right toolchain in the AmForth directory itself. This keeps the host system unaffected. The toolchain will be installed in $(AMFORTH)/toolchain/ directory. Multiple local toolchains can be installed, e.g. both the ARM and the RISCV toolchain can be installed at the same time and the make commands will use the right one depending on which MCU directory they are executed in. The default build system setup expects this configuration of the toolchain. This configuration is also used by the CI for testing and release building.

Customizing build process

To allow for personalized development settings, the Makefiles optionally include .env file (excluded from git) if it is present in the MCU directory. Note that the .env file is interpreted as a Makefile, therefore it must follow Makefile syntax. It is useful to override default settings or provide required settings that don’t change much to avoid having to provide them on the command line on each invocation. An .env file could look as follows:

# MODEM is required by `make shell` and directs amforth-shell.py to connect to the specified TTY
MODEM ?= /dev/cu.usbmodemXXX
# If you want to override the toolchain to use for Amforth build,
# TC_DIR and CROSS are variables that control that
TC_DIR = $(AMFORTH)/toolchain/riscv-none-elf-15.2.0-1
CROSS = riscv-none-elf-
# amforth-shell.py uses the EDITOR variable when it attempts to open an external editor
export EDITOR=code

The Makefiles set most variables with ?=, therefore most can be overridden by the .env file. Read the Makefile comments for more details. The Makefiles provide AMFORTH variable as a convenient way to refer to the directory where the AmForth repository was cloned.

This site uses Just the Docs, a documentation theme for Jekyll.