CamelForthRebuild - nealcrook/multicomp6809 GitHub Wiki
This page describes how to rebuild CamelForth from source using F83. It assumes that you are using Linux.
see also: CamelForthRebuildANS
You will need:
- The DOS emulator DOSBOX. Install from your package manager or download from the web.
- The chromium source, chromium.scr, from multicomp6809/camelforth/chromium.scr
- Laxen and Perry Forth 83 (F83) for the 8086 - I used Version 2.1.0. Download from https://github.com/ForthHub/F83 or from http://www.forth.org/library/eforth_SOC/eforth_SOC_source/f83/f83v2-ms.lzh
Create a directory named F83. Unpack the F83 code into that directory.
Set up DOSBOX so that drive A maps to the parent directory of F83, and drive B maps to the directory containing chromium.scr. For example, your dosbox.conf might contain lines like this:
[autoexec]
# Lines in this section will be run at startup.
# You can put your MOUNT lines here.
# Parent directory of F83
mount a: /home/me/retro
# Directory containing chromium.scr
mount b: /home/me/retro/multicomp6809/camelforth
Start up DOSBOX ("dosbox -conf dosbox_f83.conf" if you have a special config file) and from within DOSBOX type this sequence of commands:
a:
cd F83
F83 b:chromium.scr
45 load
dir 6809*
exit
The whole session should look like this:
Z:\>a:
A:\>cd F83
A:\F83>F83 b:chromium.scr
8086 Forth 83 Model
Version 2.1.0 Modified 01Jun84
45 load OFFSET isn't unique THRU isn't unique ASSEMBLER isn't unique
24 Empty DUMP isn't unique
19 Empty
1A Empty
4 Empty
5 Empty
6 Empty
7 Empty
30 Empty
Context: ASSEMBLER META FORTH ROOT
Current: ASSEMBLER WITHIN isn't unique
1F Empty # isn't unique <> isn't unique
20 Empty , isn't unique A isn't unique B isn't unique
21 Empty
22 Empty
23 Empty
24 Empty
25 Empty
26 Empty
27 Empty
28 Empty
29 Empty
2A Empty CC isn't unique
2B Empty
2C Empty
Context: META FORTH ROOT
Current: META
8 Empty
9 Empty
10 Empty
11 Empty
12 Empty CODE isn't unique
13 Empty
14 Empty
15 Empty
16 Empty EXIT isn't unique
17 Empty
18 Empty META isn't unique TARGET isn't unique ASSEMBLER isn't unique LOAD isn't unique \ isn't unique \S isn't unique CODE isn't unique EQU isn't un
ique ;C isn't unique ;CODE isn't unique BYE isn't unique RESOLVES isn't unique ORG isn't unique THRU isn't unique [COMPILE] isn't unique ( isn't uniq
ue ASM: isn't unique EMULATES isn't unique EMULATE: isn't unique ;EMULATE isn't unique DICTIONARY isn't unique PRESUME isn't unique IS-CF isn't uniqu
e AKA isn't unique
19 Empty : isn't unique ; isn't unique IMMEDIATE isn't unique DOES> isn't unique [ isn't unique ] isn't unique @ isn't unique ! isn't unique C@ isn't
unique LOAD isn't unique C! isn't unique THRU isn't unique , isn't unique C, isn't unique HERE isn't unique ALLOT isn't unique CREATE isn't unique
20 Empty ' isn't unique ['] isn't unique CELL isn't unique ALIGN isn't unique HEX isn't unique DECIMAL isn't unique ( isn't unique \ isn't unique
21 Empty
Context: META FORTH ROOT
Current: META DUP isn't unique SWAP isn't unique .S isn't unique + isn't unique
22 Empty
23 Empty
46 Empty
2F Empty
30 Empty
64 Empty
41 Empty
42 Empty
43 Empty
44 Empty
45 Empty
46 Empty
47 Empty
48 Empty
49 Empty
4A Empty
4B Empty
4C Empty
4D Empty
4E Empty
4F Empty
50 Empty
51 Empty
52 Empty
53 Empty
54 Empty
85 Empty
56 Empty
57 Empty
58 Empty
59 Empty
5A Empty
5B Empty
5C Empty
5D Empty
5E Empty
5F Empty
60 Empty
61 Empty
62 Empty
63 Empty
64 Empty
65 Empty
66 Empty
67 Empty
68 Empty
69 Empty
6A Empty
6B Empty
6C Empty
6D Empty
6E Empty
6F Empty
70 Empty
71 Empty
72 Empty WORDS isn't unique
73 Empty
74 Empty
75 Empty
76 Empty
50 Empty
33 Empty
34 Empty
35 Empty
36 Empty
37 Empty
38 Empty
39 Empty
3A Empty
3B Empty
121 Empty
7A Empty
7B Empty
7C Empty
7D Empty
7E Empty
7F Empty
174 Pages
A:\F83>dir 6809*
Directory of A:\F83\.
6809M HEX 23,053 04-01-2017 17:33
1 File(s) 23,053 Bytes.
0 Dir(s) 262,111,744 Bytes free.
A:\F83>exit
The result of running these commands is that a new executable image is built within chromium.scr (so that chromium.scr might be altered in content though not in size) and is then exported as 6809M.HEX.
chromium.scr also contains the source code, which is arranged in a set of "screens" each of which is 1Kbytes. Before typing "45 LOAD" you can type "45 LIST" to see the load screen (the screen that pulls in all the other screens). The message eg "16 Empty" is a diagnostic message to indicate that the stack is empty (as it should be) at the end of -- in this case -- loading screen 16.
The source file "chromium.scr" (run it through multicomp6809/bin/forth_block2ascii to inspect it/print it more easily) contains FORTH code that runs on F83 (the host system). This code has 3 separate elements:
- a metacompiler (called "chromium") which has the ability to create a memory image of a new FORTH (CamelFORTH) for a target system
- a 6809 assembler, allowing definitions for the target system to be written in assembler (needed for some of the very low-level components of the target FORTH system
- camelforth itself, written in a combination of 6809 assembler and FORTH
The "meta" part of all of this is that a lot of the FORTH definitions are in terms of other previously-defined definitions. Each definition that is created has to have some kind of presence both in the host system and in the target system.
The final result is a memory image (for the target system) that gets written out as a HEX file designed to execute from ROM. The target system does not include the assembler. One of my early goals was to add it in, but I soon realised that there was not enough free space in the ROM to hold it. I made other enhancements instead, focussed on using the SD card to load and store FORTH source and precompiled blobs of FORTH code. As a result, the current ROM for multicomp09 has ~16 bytes of free space.
You can use the ROM-based commands to inspect source code (stored on the SD Card) or to compile a bunch of utilities -- including an editor -- which are stored on the SD card. See camelforth#editor-and-utilities-for-camelfortheditor-and-utilities-for-camelforth
Do I need to do this?
There should be no need to rebuild the code from source. Because there is very little free space in the ROM (as mentioned above) it's best to make extensions through files stored on SD Card in source or binary (precompiled) form.
Rebuild CamelForth at a different origin
For debug purposes, I wanted a version of CamelForth that loaded and executed at a different address: 2000H instead of E000H. I kept the format of the image identical - so that it still has a "hole" for I/O at FFExH and still contains vectors at 2FFxH, even though neither of those are applicable for an image at 2000H.
These changes are needed:
- On screen 45, line 14:
HEX 2000 2000 HEXFILE 6809M.HEX
(the first 2000 is the new origin) - On screen 46, line 1:
HEX 2000 3FFF DICTIONARY ROM ROM
- On screen 49, line 12:
HERE 03FF0 ORG \ 6809 hardware vectors
- On screen 116, line 3:
." 6809 CamelForth v1.1 24 May 20" CR
(change it in some way so you can distinguish it from the ROM version, but don't change the length of the string!)
after building with the new code, the image will be exported as 6809M.HEX and will also be in the .scr file -- but its location in the .scr file moves depending upon its origin. The .scr file will still contain a pre-existing binary for the previous build done at E000. If you want to get the image out of the .scr file, make sure that you get the correct image (the script create_sd_image has an example of extracting the correct image from the .scr file).