mirror of
https://github.com/forth-ev/VolksForth.git
synced 2024-11-25 10:30:57 +00:00
112 lines
4.1 KiB
Org Mode
112 lines
4.1 KiB
Org Mode
#+TITLE: VolksForth MS-DOS README
|
|
#+AUTHOR: Carsten Strotmann, Philip Zembrod
|
|
#+DATE: <2022-03-13 Sun>
|
|
|
|
* Refactoring in progress
|
|
|
|
MSDOS VolksForth is currently in transition towards make based
|
|
and stream file (.fth) based builds.
|
|
|
|
* Documentation for make based builds
|
|
|
|
The central Makefile is written for GNU make on Linux and uses
|
|
the DOS emulator dosbox to run VolksForth and Metacompiler
|
|
binaries for building new VolksForth binaries and for running
|
|
tests. The make rules also use several Linux tools, e.g.
|
|
bash, Python, grep or dos2unix.
|
|
|
|
volks4th.com is the old checked-in full VolksForth binary
|
|
with editor etc, manually compiled from block sources as
|
|
described in the "Previous .fb-based manual build instructions".
|
|
It is intended to remain untouched throughout the transition
|
|
period until it can be safely replaced by new .fth-based
|
|
kernels with build-in .fth interface.
|
|
|
|
** Binary make targets
|
|
=make v4th.com=
|
|
builds the new minimal VolksForth kernel v4th.com
|
|
from .fth sources using metafile.com. v4th.com does not have the block
|
|
words and the buffer mechanism anymore. The only way to load code from
|
|
files is via =include filename.fth=.
|
|
=make v4thblk.com=
|
|
builds the new minimal VolksForth kernel v4thblk.com
|
|
from .fth sources using metafile.com. v4thblk.com contains the block
|
|
words and the buffer mechanism and can load and include both .fth
|
|
stream sources and .fb block sources.
|
|
=make metafile.com=
|
|
builds the metacompiler with included .fth file interface.
|
|
It is used to build v4th.com, so metafile.com will be built
|
|
as part of the make rule for v4th.com. Note: metafile.com
|
|
is mostly still built from meta.fb, i.e. from block sources.
|
|
=make o4th.com=
|
|
builds a new minimal VolksForth kernel from kernel.fb, i.e.
|
|
from block sources. This is equivalent to the previous
|
|
"How to meta-compile a new kernel" instruction.
|
|
=make v4thfile.com=
|
|
adds the .fth file interface to the old volks4th binary.
|
|
|
|
** Test make targets
|
|
=make test=
|
|
runs all current tests.
|
|
=make test-std.result=
|
|
runs v4th.com through the standard set of unit tests, without the block
|
|
tests, of course
|
|
=make test-blk.result=
|
|
runs v4thblk.com through full set of unit tests, including the block
|
|
tests.
|
|
=make test-volks4th-min.result=
|
|
runs the same initial minimal set of unit tests on v4thfile.com
|
|
which is the old volks4th.com binary with added .fth file interface.
|
|
|
|
* Previous .fb-based manual build instructions
|
|
|
|
** How to meta-compile a new kernel
|
|
|
|
After making changes the the Forth kernel source in =kernel.fb=,
|
|
restart =volksforth.com= to have a clean system and compile a new
|
|
"minimal" kernel with =include kernel.fb=. This will create a new =FORTH.COM= executable.
|
|
|
|
** creating a minimal system with a simple editor
|
|
|
|
Execute =forth.com include minimal.sys= to generate the file =minimal.com= which contains a minimal VolksForth system with the
|
|
Retro-Forth editor
|
|
https://fossil.forth-ev.de/volksforth/wiki?name=Atari8bit-retrofortheditor
|
|
|
|
This system can be used to edit the file =volksforth.sys= or other
|
|
Forth source block files needed to create a full VolksForth system.
|
|
|
|
** creating a full VolksForth system from the minimal kernel
|
|
|
|
Execute =forth.com include volks4th.sys= to create a new fully
|
|
equipped VolksForth executable =volks4th.com=.
|
|
|
|
** creating a version of VolksForth that works with emu2
|
|
|
|
EMU2 is a nice PC Emulator that can run MS-DOS console applications
|
|
as Linux/MacOS/Windows console applications. EMU2 can be found at
|
|
https://github.com/dmsc/emu2
|
|
|
|
The standard Keyboard-Interface of VolksForth (BDOS) does not work
|
|
with EMU2, however it is possible to switch to the simpler BIOS
|
|
keyboard interface. For that, comment out the blocks #114 and #115
|
|
by placing =\\= at the beginning of the first row of these blocks
|
|
and comment in block #116 by changing the =\\= in the first row to =\=. (=\= is "skip to end of line" comment, while =\\= is the "skip
|
|
to end of current block" commend).
|
|
|
|
The downside of this change is that the VolksForth full screen
|
|
editor does not work anymore, as the BIOS interface does not support
|
|
special keys like cursor or function keys. As a replacement, the
|
|
Retro-Forth Editor =rfe.fb= or some other Forth Editor can be used.
|