retroforth/doc/html/chapters/building/advanced.html
crc e89789839b rebuild .html documentation; correct a filename reference (Rx.md -> image/retro.muri) reported by Martin Hohmann-Marriott
FossilOrigin-Name: 429b138d84f0284a5f7054165c02a40f33ecbe919165eebc5271a07a367864bc
2022-06-03 10:41:52 +00:00

152 lines
6.7 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>.</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><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/>
<br/><br/>
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 <span class="tt">ENABLED</span>:
<br/><br/>
<tt class='indentedcode'>ENABLED&nbsp;?=</tt>
<tt class='indentedcode'>ENABLED&nbsp;+=&nbsp;-DENABLE_FLOATS</tt>
<tt class='indentedcode'>ENABLED&nbsp;+=&nbsp;-DENABLE_FILES</tt>
<tt class='indentedcode'>ENABLED&nbsp;+=&nbsp;-DENABLE_UNIX</tt>
<tt class='indentedcode'>ENABLED&nbsp;+=&nbsp;-DENABLE_RNG</tt>
<tt class='indentedcode'>ENABLED&nbsp;+=&nbsp;-DENABLE_CLOCK</tt>
<tt class='indentedcode'>ENABLED&nbsp;+=&nbsp;-DENABLE_SCRIPTING</tt>
<tt class='indentedcode'>ENABLED&nbsp;+=&nbsp;-DENABLE_SIGNALS</tt>
<tt class='indentedcode'>#&nbsp;ENABLED&nbsp;+=&nbsp;-DENABLE_SOCKETS</tt>
<tt class='indentedcode'>#&nbsp;ENABLED&nbsp;+=&nbsp;-DENABLE_MULTICORE</tt>
<tt class='indentedcode'>ENABLED&nbsp;+=&nbsp;-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/>
<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/>
<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&nbsp;OPTIONS=-DBIT64</tt>
<br/><br/>
<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&nbsp;OPTIONS="-DSTACK_DEPTH=4000&nbsp;-DADDRESSES=500</tt>
<br/><br/>
<br/><br/>
You can also alter the image size. Again, for a one-off build:
<br/><br/>
<tt class='indentedcode'>make&nbsp;OPTIONS=-DIMAGE_SIZE=4000000</tt>
<br/><br/>
Would build a system with a maximum image size of 4,000,000 cells.
<br/><br/>
<br/><br/>
If you do any of these routinely, edit the Makefile to include them.
<br/><br/>
<tt class='indentedcode'>OPTIONS&nbsp;?=</tt>
<tt class='indentedcode'>OPTIONS&nbsp;+=&nbsp;-DBIT64</tt>
<tt class='indentedcode'>OPTIONS&nbsp;+=&nbsp;-DSTACK_DEPTH=4000</tt>
<tt class='indentedcode'>OPTIONS&nbsp;+=&nbsp;-DADDRESSES=500</tt>
<tt class='indentedcode'>OPTIONS&nbsp;+=&nbsp;-DIMAGE_SIZE=4000000</tt>
<br/><br/>
<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&nbsp;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>