160 lines
7.1 KiB
HTML
160 lines
7.1 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
|
<title>doc/book/building/advanced</title>
|
|
<style type="text/css">
|
|
|
|
* { color: #000; background: #fff; max-width: 700px; }
|
|
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
|
white-space: pre; display: block; width: 100%; }
|
|
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
|
.codeblock {
|
|
background: #dedede; color: #111; font-family: monospace;
|
|
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
|
padding: 7px;
|
|
display: block;
|
|
}
|
|
|
|
.indentedlist { margin-left: 2em; color: #000; }
|
|
|
|
span { white-space: pre; }
|
|
.text { color: #000; white-space: pre; background: #dedede; }
|
|
.colon { color: #000; background: #dedede; }
|
|
.note { color: #000; background: #dedede; }
|
|
.str { color: #000; text-decoration: underline; background: #dedede; }
|
|
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
|
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
|
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
|
.fetch { color: #000; font-style: italic; background: #dedede; }
|
|
.store { color: #000; font-style: italic; background: #dedede; }
|
|
.char { color: #000; background: #dedede; }
|
|
.inst { color: #000; background: #dedede; }
|
|
.defer { color: #000; background: #dedede; }
|
|
.imm { color: #000; font-weight: bold; background: #dedede; }
|
|
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
|
|
|
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
|
|
|
.h1, .h2, .h3, .h4 { white-space: normal; }
|
|
.h1 { font-size: 125%; }
|
|
.h2 { font-size: 120%; }
|
|
.h3 { font-size: 115%; }
|
|
.h4 { font-size: 110%; }
|
|
.hr { display: block; height: 2px; background: #000000; }
|
|
</style>
|
|
</head><body>
|
|
<p><span class="h1">Customizing the Build</span>
|
|
<br/><br/>
|
|
While a simple <span class="tt">make</span> will suffice for building Retro, there
|
|
are a number of ways to customize the build to your needs.
|
|
<br/><br/>
|
|
In this chapter, replace <span class="tt">Makefile</span> with <span class="tt">GNUmakefile</span> if you
|
|
are using GNU Make (most Linux and macOS users will probably
|
|
be using this).
|
|
<br/><br/>
|
|
<span class="h2">I/O Devices</span>
|
|
<br/><br/>
|
|
Many of the I/O devices are optional. The most common ones are
|
|
enabled by default in the Configuration.mk. Look for the lines
|
|
starting with <span class="tt">ENABLED</span>:
|
|
<br/><br/>
|
|
<tt class='indentedcode'>ENABLED ?=</tt>
|
|
<tt class='indentedcode'>ENABLED += -DENABLE_FLOATS</tt>
|
|
<tt class='indentedcode'>ENABLED += -DENABLE_FILES</tt>
|
|
<tt class='indentedcode'>ENABLED += -DENABLE_UNIX</tt>
|
|
<tt class='indentedcode'>ENABLED += -DENABLE_RNG</tt>
|
|
<tt class='indentedcode'>ENABLED += -DENABLE_CLOCK</tt>
|
|
<tt class='indentedcode'>ENABLED += -DENABLE_SCRIPTING</tt>
|
|
<tt class='indentedcode'>ENABLED += -DENABLE_SIGNALS</tt>
|
|
<tt class='indentedcode'># ENABLED += -DENABLE_SOCKETS</tt>
|
|
<tt class='indentedcode'># ENABLED += -DENABLE_MULTICORE</tt>
|
|
<tt class='indentedcode'>ENABLED += -DENABLE_FFI</tt>
|
|
<br/><br/>
|
|
Lines starting with a <span class="tt">#</span> are commented out and will not be
|
|
processed when building. Here you can easily enable or disable
|
|
specific devices in the VM.
|
|
<br/><br/>
|
|
You should also remove any disabled devices from the <span class="tt">DEVICES ?=</span>
|
|
lines if you want to exclude the Forth part of them from the image.
|
|
<br/><br/>
|
|
Note: on platforms (like Linux) that lack the <span class="tt">strl*</span> functions
|
|
from libc, make sure the <span class="tt">ENABLED += -DNEEDS_STRL</span> is not commented
|
|
out.
|
|
<br/><br/>
|
|
For the FFI, on Linux, you will need to link with <span class="tt">libdl</span>. Edit the
|
|
<span class="tt">GNUmakefile</span> to uncomment the <span class="tt"># LIBDL += -ldl</span> line.
|
|
<br/><br/>
|
|
If you want to build with sockets support, uncomment the
|
|
<span class="tt"># ENABLED += -DENABLE_SOCKETS</span> and <span class="tt">DEVICES += interface/sockets.retro</span>
|
|
lines before building.
|
|
<br/><br/>
|
|
<span class="h2">Compiler Flags</span>
|
|
<br/><br/>
|
|
You may need or want to adjust the compiler flags. In the first
|
|
section of the <span class="tt">Makefile</span>, look for <span class="tt">CFLAGS</span> and add/change as
|
|
desired to override the defaults.
|
|
<br/><br/>
|
|
<span class="h2">VM Tweaks</span>
|
|
<br/><br/>
|
|
<span class="h3">64-Bit</span>
|
|
<br/><br/>
|
|
A standard Retro system uses a 32-bit word size. You can increase
|
|
this to 64-bit though. For a one-off build:
|
|
<br/><br/>
|
|
<tt class='indentedcode'>make OPTIONS=-DBIT64</tt>
|
|
<br/><br/>
|
|
<span class="h3">Stack Size</span>
|
|
<br/><br/>
|
|
You can alter the stack sizes by defining <span class="tt">STACK_DEPTH</span> and
|
|
<span class="tt">ADDRESSES</span>. For a one-off build with a max stack depth of 4000
|
|
items and 500 addresses on the return stack:
|
|
<br/><br/>
|
|
<tt class='indentedcode'>make OPTIONS="-DSTACK_DEPTH=4000 -DADDRESSES=500</tt>
|
|
<br/><br/>
|
|
<span class="h3">Image Size</span>
|
|
<br/><br/>
|
|
You can also alter the image size. Again, for a one-off build:
|
|
<br/><br/>
|
|
<tt class='indentedcode'>make OPTIONS=-DIMAGE_SIZE=4000000</tt>
|
|
<br/><br/>
|
|
Would build a system with a maximum image size of 4,000,000 cells.
|
|
<br/><br/>
|
|
<span class="h3">Update the Makefile</span>
|
|
<br/><br/>
|
|
If you do any of these routinely, edit the Makefile to include them.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>OPTIONS ?=</tt>
|
|
<tt class='indentedcode'>OPTIONS += -DBIT64</tt>
|
|
<tt class='indentedcode'>OPTIONS += -DSTACK_DEPTH=4000</tt>
|
|
<tt class='indentedcode'>OPTIONS += -DADDRESSES=500</tt>
|
|
<tt class='indentedcode'>OPTIONS += -DIMAGE_SIZE=4000000</tt>
|
|
<br/><br/>
|
|
<span class="h2">Further Image Customization</span>
|
|
<br/><br/>
|
|
You can customize the image further by having the build process
|
|
include your code in the image.
|
|
<br/><br/>
|
|
In the top level directory is a <span class="tt">package</span> directory containing
|
|
a file named <span class="tt">list.forth</span>. You can add files to compile into
|
|
your system by adding them to the <span class="tt">list.forth</span> and rebuilding.
|
|
<br/><br/>
|
|
Example:
|
|
<br/><br/>
|
|
If you have wanted to include the <span class="tt">NumbersWithoutPrefixes.forth</span>
|
|
example, add:
|
|
<br/><br/>
|
|
<tt class='indentedcode'>~~~</tt>
|
|
<tt class='indentedcode'>'example/NumbersWithoutPrefixes.forth include</tt>
|
|
<tt class='indentedcode'>~~~</tt>
|
|
<br/><br/>
|
|
To the start of the <span class="tt">list.forth</span> file and then run <span class="tt">make</span> again.
|
|
<br/><br/>
|
|
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 <span class="tt">package/extensions</span> and running
|
|
<span class="tt">make update-extensions</span>
|
|
<br/><br/>
|
|
After rebuilding, the newly built <span class="tt">bin/retro</span> will now include
|
|
your additions.
|
|
</p>
|
|
</body></html>
|