113 lines
3.3 KiB
Text
113 lines
3.3 KiB
Text
# 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.
|