retroforth/doc/book/building/advanced

114 lines
3.3 KiB
Text
Raw Normal View History

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