Customizing the Build

While a simple make will suffice for building Retro, there are a number of ways to customize the build to your needs.

In this chapter, replace Makefile with GNUmakefile if you are using GNU Make (most Linux and macOS users will probably be using this).

I/O Devices

Many of the I/O devices are optional. The most common ones are enabled by default in the Makefile. Look near the end of the top section for lines starting with ENABLED:

ENABLED ?= ENABLED += -DENABLE_FLOATS ENABLED += -DENABLE_FILES ENABLED += -DENABLE_UNIX ENABLED += -DENABLE_RNG ENABLED += -DENABLE_CLOCK ENABLED += -DENABLE_SCRIPTING ENABLED += -DENABLE_SIGNALS # ENABLED += -DENABLE_SOCKETS # ENABLED += -DENABLE_MULTICORE ENABLED += -DENABLE_FFI

Lines starting with a # are commented out and will not be processed when building. Here you can easily enable or disable specific devices in the VM.

You should also remove any disabled devices from the DEVICES ?= lines if you want to exclude the Forth part of them from the image.

Note: on platforms (like Linux) that lack the strl* functions from libc, make sure the ENABLED += -DNEEDS_STRL is not commented out.

For the FFI, on Linux, you will need to link with libdl. Edit the GNUmakefile to uncomment the # LIBDL += -ldl line.

If you want to build with sockets support, uncomment the # ENABLED += -DENABLE_SOCKETS and DEVICES += interface/sockets.retro lines before building.

Compiler Flags

You may need or want to adjust the compiler flags. In the first section of the Makefile, look for CFLAGS and add/change as desired to override the defaults.

VM Tweaks

64-Bit

A standard Retro system uses a 32-bit word size. You can increase this to 64-bit though. For a one-off build:

make OPTIONS=-DBIT64

Stack Size

You can alter the stack sizes by defining STACK_DEPTH and ADDRESSES. For a one-off build with a max stack depth of 4000 items and 500 addresses on the return stack:

make OPTIONS="-DSTACK_DEPTH=4000 -DADDRESSES=500

Image Size

You can also alter the image size. Again, for a one-off build:

make OPTIONS=-DIMAGE_SIZE=4000000

Would build a system with a maximum image size of 4,000,000 cells.

Update the Makefile

If you do any of these routinely, edit the Makefile to include them.

OPTIONS ?= OPTIONS += -DBIT64 OPTIONS += -DSTACK_DEPTH=4000 OPTIONS += -DADDRESSES=500 OPTIONS += -DIMAGE_SIZE=4000000

Further Image Customization

You can customize the image further by having the build process include your code in the image.

In the top level directory is a package directory containing a file named list.forth. You can add files to compile into your system by adding them to the list.forth and rebuilding.

Example:

If you have wanted to include the NumbersWithoutPrefixes.forth example, add:

~~~ 'example/NumbersWithoutPrefixes.forth include ~~~

To the start of the list.forth file and then run make again.

If you have an existing Retro build and want to have the system handle loading extensions with less manual intervention by putting the source files in package/extensions and running make update-extensions

After rebuilding, the newly built bin/retro will now include your additions.