From da67e34f432e75057caa1cfd08e76143227769b2 Mon Sep 17 00:00:00 2001 From: crc Date: Mon, 18 Mar 2019 20:24:55 +0000 Subject: [PATCH] book: some brief notes on the tools, building custom image FossilOrigin-Name: 83d9ac7ce802062c18a9f46d9cef44d2051b8503af8c5c1b60078407a78b11d3 --- RETRO-Book.md | 53 +++++++++++++++++++++++++++++++++++++++++++ book/Additional-Tools | 33 +++++++++++++++++++++++++++ book/Advanced-Builds | 20 ++++++++++++++++ 3 files changed, 106 insertions(+) diff --git a/RETRO-Book.md b/RETRO-Book.md index e7729a5..76e03dd 100644 --- a/RETRO-Book.md +++ b/RETRO-Book.md @@ -1256,5 +1256,58 @@ The buffers at the end of memory will resize when specific variables related to them are altered. +# Additional Tools +In addition to the core `retro` binary, the `bin` directory +will contain a few other tools. + +## retro + +This is the main RETRO binary. + +## retro-describe + +This is a program that looks up entries in the Glossary. + +## retro-embedimage + +This is a program which generates a C file with the ngaImage +contents. It's used when building `retro`. + +## retro-extend + +This is a program which compiles code into the ngaImage. +It's used when building `retro` and when you want to make a +standalone image with custom additions. + +## retro-muri + +This is the assembler for Nga. It's used to build the initial +RETRO kernel and can be used by other tools as well. + +## retro-unu + +This is the literate source extraction tool for RETRO. It +is used in building `retro`. + +# Advanced Builds + +For users of BSD, Linux, macOS, you can customize the image at +build time. + +In the top level directory is a `packages` directory containing +a file named `list`. You can add files to compile into your +system by adding them to the `list` and rebuilding. + +Example: + +If you have wanted to include the NumbersWithoutPrefixes.forth +example, add: + + ~~~ + 'example/NumbersWithoutPrefixes.forth include + ~~~ + +To the start of the `list` file and then run `make` again. The +newly built `bin/retro` will now include your additions. diff --git a/book/Additional-Tools b/book/Additional-Tools index e69de29..0836ca5 100644 --- a/book/Additional-Tools +++ b/book/Additional-Tools @@ -0,0 +1,33 @@ +# Additional Tools + +In addition to the core `retro` binary, the `bin` directory +will contain a few other tools. + +## retro + +This is the main RETRO binary. + +## retro-describe + +This is a program that looks up entries in the Glossary. + +## retro-embedimage + +This is a program which generates a C file with the ngaImage +contents. It's used when building `retro`. + +## retro-extend + +This is a program which compiles code into the ngaImage. +It's used when building `retro` and when you want to make a +standalone image with custom additions. + +## retro-muri + +This is the assembler for Nga. It's used to build the initial +RETRO kernel and can be used by other tools as well. + +## retro-unu + +This is the literate source extraction tool for RETRO. It +is used in building `retro`. diff --git a/book/Advanced-Builds b/book/Advanced-Builds index e69de29..365afdc 100644 --- a/book/Advanced-Builds +++ b/book/Advanced-Builds @@ -0,0 +1,20 @@ +# Advanced Builds + +For users of BSD, Linux, macOS, you can customize the image at +build time. + +In the top level directory is a `packages` directory containing +a file named `list`. You can add files to compile into your +system by adding them to the `list` and rebuilding. + +Example: + +If you have wanted to include the NumbersWithoutPrefixes.forth +example, add: + + ~~~ + 'example/NumbersWithoutPrefixes.forth include + ~~~ + +To the start of the `list` file and then run `make` again. The +newly built `bin/retro` will now include your additions.