retroforth/BUILDING.md
crc 6bc6d0ced0 add notes on Python, C# implementations to BUILDING
FossilOrigin-Name: da06b8a3ce746eff599c8bc9b026b74b8b66695e214e1246950aa62d24213b2b
2019-02-07 02:21:50 +00:00

169 lines
3.2 KiB
Markdown

# Building RETRO
## Requirements
- c compiler (tested: clang, tcc, gcc)
- make
- standard unix shell
## Process
Run `make`.
This will build the toolchain and then the main `retro`
executable.
## Executables
In the `bin/` directory:
retro
retro-unu
retro-muri
retro-extend
retro-embedimage
# Alternate Interfaces
The main interface, rre, is built as the `retro`
executable. But there are other options:
## retro-repl
A basic interactive system can be built by using:
make bin/retro-repl
This requires a copy of `ngaImage` to be in the current
directory.
## retro-ri
`ri` is a full screen, curses based interface to RETRO.
It provides a display like:
+-------------------------------+
| ... output ... |
| |
| |
| |
+-------------------------------+
| status |
+-------------------------------+
| input |
+-------------------------------+
Input is processed as it is being entered with output
displayed above. `ri` is different from the other user
interfaces as it provides a means of switching between
five separate images.
Additional Dependencies:
- curses
To build this:
make bin/retro-ri
## Barebones
This is a minimal version of the `retro-repl`. It keeps
the C portion as short as possible, making it a useful
starting point for new interfaces.
To build:
make bin/retro-barebones
## retro-compiler
This is a turnkey compiler. It can compile a new executable
bundling a Retro VM and image.
Requirements:
- BSD or Linux
- objcopy in $PATH
To build:
make bin/retro-compiler
Example use:
1. Given a source file like "Hello.forth":
~~~
:hello 'hello_world! s:put nl ;
~~~
2. Use:
./bin/retro-compiler Hello.forth hello
The first argument is the source file, the second is the
word to run on startup.
3. Run the generated `a.out`
Limits:
This only supports the core words ('all' interface) and the
file i/o words. Support for other I/O extensions will be
added in the future.
## RETRO12.html
There is a JavaScript and HTML based interface. To
build this:
make bin/RETRO12.html
It is tested on Chrome and Safari. The interface is
based on the UI used on the iOS and macOS versions,
presenting a dual-pane model with an editor to the
left, an output area to the right, and a listener
at the bottom.
## Pascal
There is a Pascal version of `retro-repl`.
Dependencies:
- freepascal
Building:
cd interfaces/pascal
fpc listener.lpr
This will require a copy of the `ngaImage` in the
current directory.
## Python: retro.py
This is an implementation of `retro-repl` in Python. As
with `retro-repl` it requires the `ngaImage` in the current
directory when starting.
## C#: retro.cs
This is an implementation of `retro-repl` in C#. As with
`retro-repl` it requires the `ngaImage` in the current
directory when starting.
Building:
csc retro.cs
You'll need to make sure your path has the CSC.EXE in it,
or provide a full path to it. Something like this should
reveal the path to use:
dir /s %WINDIR%\CSC.EXE
I've only tested building this using Microsoft's .NET tools.
It should also build and run under Mono.