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:

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:

  1. a metacompiler (called "chromium") which has the ability to create a memory image of a new FORTH (CamelFORTH) for a target system
  2. 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
  3. 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:

  1. On screen 45, line 14: HEX 2000 2000 HEXFILE 6809M.HEX (the first 2000 is the new origin)
  2. On screen 46, line 1: HEX 2000 3FFF DICTIONARY ROM ROM
  3. On screen 49, line 12: HERE 03FF0 ORG \ 6809 hardware vectors
  4. 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).