Development Environment for Forth?

I believe that Forth like any other programming language benefits from a well organised project development environment.

This article is a work in progress because although my own forth development environment is mostly finished and does pretty much what I want, it’s going to take a while to describe it here.

My Current Working Design Environment @October 2018

Picture: Gnu Screen/Gvim

_images/forth-devenv-blinky-multitask.jpg

The code shown in the Gnu Screen window is from my svd2forth showing my development version which includes register legends to make real time debugging faster and easier. In this instance it’s simply blinking the green led on a STM32F0 Discovery board.

  1. Gnu Screen is controlled from by the GVIM editor while uploading Fourth Sourcecode, but also manually available as a normal terminal by mousing over.
  2. I edit Forth Code in GVIM then click on the Gvim “make’ icon when ready to test the code on the target. This uploads the code at 460800 Baud with RTS handshaking via Gnu Screen using a slightly modified STM32F051-RA Kernel.

When a code error occurs the upload is stopped at the offending line via RTS handshaking. After I read it, I press a pushbutton switch located near the target which bypasses the RTS handshaking hold allowing the upload to finish. I then press the reset button of the target, because it will be full of errors related to the initial problem, fix the code and repeat this cycle until I get what I want. All test code is run from RAM on the target, and as Words are tested good, they are moved to Flash so a target reset does not require good Words to be reloaded.

This method is the fasted I’ve found and with RTS handshaking my STM32F051’s running at their maximum speed of 48MHz never choke on large Words as Mecrisp-Stellaris compiles them on the fly while uploading. When a large and complex Word is encountered the GNU Screen Window freezes for a instant then resumes scrolling uploaded code faster than I can read it.

Initially I used a few dedicated Serial Terminals such as e4thcom but although e4thcom is quite fast, it’s slightly slower than my system because it only runs at a maximum of 115K baud and has to parse Mecrisp-Stellaris code errors in the terminal RX stream so as to be able to stop uploads when the inbuilt Mecrisp-Stellaris compiler detects them.

Frankly if one can’t detect code errors automatically during a fast source upload, Mecrisp-Stellaris is going to be a very disappointing experience ihmo. I believe watching a large Forth program upload slowly so errors can be observed just isn’t realistic either.

In my experience this system is much faster than using C and GDB on the same machine (A Intel i7) workstation.

In fact, the above system is perfectly responsive on a Raspberry Pi V3 with no delays. Try running the free Atollic TrueStudio for STM32 on a RPI ? I bet it takes a week just to load, and that’s not including CubeMX.

This system also uses the Mecrisp-Stellaris Cooperative Multitasker code, which is loaded after the test code. This is all transparent to me as it’s orchestrated by the Makefile controlling uploads via Gnu Screen, which loads the muli-tasking code last.

This is shown in the contrived example where the Word “RCC_AHBENR.” is last in the source, but the multasking code is uploaded after “RCC_AHBENR.” is executed and shows the state of the RCC_AHBENR register at that time.

The Green led is now blinking.

A Forth Project Build Script With Libraries

Exerpt from a post made by Julian Foundran (Nov2017) in comp.lang.forth which makes a lot of sense to me.

My point is just that if you care about Forth having a library platform, that you shouldn't worry too much about the technical requirements of the old loose-leaf library systems. A much more popular target today is, at a unix prompt:

 * $ forthbuild new my-cool-app
 * $ cd my-cool-app
 * $ forthbuild install a-long list-of libraries
 * $ vi my-app.fs

Which creates a workspace and then populates it with some libraries that are unique to that workspace.

Those libraries might be, as in http://theforth.net/package/f , right under my-cool-app/forth-packages/

Essential Features

This is a list of all the attributes I consider essential in any development environment, not just Forth

FAST project creation

When I start a new project, I create its directory then run a project builder shell script. The new project directory will then be populated with the sub-directories, templates, shell scripts and files, I typically use in all my projects. The scriopt is finished 0.3 seconds later and I can begin coding.

  • Code Versioning System: set up and running, with the initial project files already committed. I use Fossil for this.
  • Schematic Capture: with a various templates ready for me to begin testing and documenting. Usually I start with a STM32F0 Discovery Board, so that’s my main schematic template. gEDA is what I use.
  • Directories: ready to receive files as I create them, i.e. pdf, flowchart, pics, text, misc
  • A library symlink to my versioned STM32F Mecrisp-Stellaris library so I can pull them in as needed
  • Sphinx Documentation system: (Sphinx is used to create this site) ready to start adding documents.
  • e4thcom Serial Terminal: which automatically opens in the new project directory.
  • Editor: which will open with several files, pre-created and pre-named by the project builder shell script. I use Gvim.
  • Svd2forth files to suit the MCU. These are used to generate Memory Mapped Register words, preloaded before the actual project files and controlled by a Makefile.
  • Finally, a z-WARNING-DESTROY-test-project.fossil.sh shell script that will remove every project file, the Fossil repository and finally the project directory itself. This has a “are you sure” confirmation before proceeding. Once a project is underway and I’m happy with it, I may manually delete the z-WARNING-DESTROY-test-project.fossil.sh shell script just to be on the safe side. It’s saved in the Fossil Code Repo anyway if I need it later.

The project builder shell script also refuses to dump all these files into a non-empty directory.

Project Builder Shell Script

Not quite ready for release yet, and it may never be as it’s tailored for my use, which is bound to be quite different to what you want. In any event, it’s not hard to do this with a SH script and make exactly what you want. My SH script that does this is only 173 lines of code.

Operation

I create a directory and type ‘forthme’ in it and 0.3 of a second later, the directory looks like the test-project directory listing below.

That 0.3 seconds includes populating the new project directory and versioning it. All the files have the directory name (the project name) and they’re all added to Fossil and committed before I enter a line of code. In fact it’s all done before my heart has had time for one beat.

I can now start typing Forth code into a automagically opened terminal onto the actual hardware I’ll be using and editing the project templates to suit. This includes the memory mapped Forth Register words for the MCU, a Schematic Diagram, possibly a Sphinx Ebook for the product.

Because it’s versioned with Fossil, I can generate a release Tarball instantly via the Fossil project webpage as shown in this picture.

_images/fossil-1.jpg

It’s all done with one SH script, no Java, no Eclipse, no delay.

Test-Project Directory Listing

test-project% tree -a
.
|-- .README-test-project.txt.swp
|-- .fossil-settings
|   |-- binary-glob
|   |-- crnl-glob
|   |-- ignore-glob
|   `-- ignore-glob.no-warn
|-- .fslckout
|-- Makefile
|-- README-test-project.txt
|-- STM32F051K8.txt
|-- STM32F0xx.svd
|-- STM32F0xx.svd.uf.svd
|-- e4thcom-ttyUSB0.sh
|-- e4thcom-ttyUSB1.sh
|-- e4thcom-ttyUSB2.sh
|-- edit-README-test-project.txt
|-- edit-all-files-test-project.sh
|-- edit-template.xml.sh
|-- edit-test-project.fs
|-- edit-test-project.preload.fs
|-- edit-test-project.sch.sh
|-- f051-legends.fs
|-- flowcharts
|-- gafrc
|-- lib -> /home/tp/projects/programming-languages/forth/mecrisp-stellaris/library
|-- memmap.fs
|-- misc-files
|-- mk.template.xsl
|-- pdf
|-- pics
|-- register-reference.fs
|-- registers.xsl
|-- rpi-ssh.sh
|-- schematics
|   `-- test-project.sch
|-- sphinx
|-- svdcutter.xsl
|-- svduf.xsl
|-- template.xml
|-- test-project.fs
|-- test-project.preload.fs
|-- test-project.txt
|-- text
`-- z-WARNING-DESTROY-test-project.fossil.sh

CrystalScad

A similar technique is used with CrystalScad

https://github.com/jglauche/CrystalScad

CrystalSCAD comes with a generator that generates project stubs automatically for you. Run this command from a terminal in the directory that you want to create a project: # crystalgen new [my_project_name]

Change [my_project_name] to the name of your project

A project named “my_project” will create those files and directories:

my_project/my_project.rb - the controller
my_project/lib/assemblies - for putting together assemblies of individual parts
my_project/lib/electronics - put electronics here
my_project/lib/hardware - put hardware parts in here
my_project/lib/printed - put parts that you want to print in here
my_project/lib/lasercut - put sheets that need to be cut (by laser or other) in here
my_project/lib/assemblies/my_project_assembly.rb - dummy assembly
my_project/lib/printed/testcube.rb - dummy printed part
my_project/my_project.observr - observer file

Open up the controller (here my_project/my_project.rb ) in the text editor of your choice. It contains the information on how to start the observer.