retroforth/doc/book/building/advanced

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