Introduction, Installation and Configuration

Introduction

VFX Forth is a fast modern Forth that compiles to native code. It is designed for large projects as well as small.

"VFX has been the most solid and cleanly designed Forth I've used in years (probably ever actually)."

VFX Forth is supplied under a free-of-charge Community licence for non-commercial use (see the license chapter) and under an Enterprise licence for commercial use. There are versions for Windows, macOS, x86 Linux and ARM Linux (including Raspberry Pi).

Installation

VFX Forth

Install VFX Forth for Mac OS X either from the package file or from the tarball. Then follow the on-screen instructions.

Directory structure

The main installed directory (folder) structure looks like this:


/usr/local/bin  - issue binaries
~/VfxForth/
  Doc
    AnsForth.Htm - ANS Forth HTML documentation
    VfxLin.htm   - VFX Forth HTML documentation
  Bin     - development binaries (not all versions)
  Examples - Examples to look at and use
    - has subdirectories
  Lib      - library of tools maintained by MPE
    CIAO  - C Inspired Active Objects OOP package
    FSL   - A port of the Forth Scientific Library
    GENIO - Examples of Generic I/O drivers
    OOP   - A Neon-style OOP package
    Osx32 - Osx specific code
      Cocoa - interface to Cocoa
    x86   - x86 specific code
  Sources  - source code if applicable
    - has subdirectories
  Kernel   - source code if applicable
    - has subdirectories
  VFXBase  - source code if applicable
    - has subdirectories
  TOOLS    - useful third party O/S specific tools
           - not present in all versions
  XTRA     - Additional third party O/S specific tools
           - not present in all versions

Executable file naming converntion

Binary file names are of the form

  VfxForth<t>_<cpu>_<os>.<fe>

e.g.

  VfxForthK_x86_win.exe

Where:


  <t>   = null for main binary
        = K for kernel
        = KH for high kernel (for shared library builds)
        = B  for base version (Windows only)
  <cpu> = x86 for 32 bit Intel i32
        = x64 for 64 bit AMD/Intel
        = arm for 32 bit ARM CPUs
        = arm64 for 64 bit ARM/Cortex CPUs
  <os>  = win for Windows
        = mac for macOS
        = lin for Linux
  <fe>  = exe for Windows PE and PE+
        = elf for Unices/Linuces
        = mo  for Mach-O files

The installer scripts should have created a short cut for you, either vfxforth or VfxForth, depending on the operating system.

Executable files

Executables and shared libraries are in the folder ~/VfxForth/Bin. The installation system also places them in /usr/local/bin or /usr/lib, which is in the executable search order. The change from /usr/bin to /usr/local/bin was required for OS X 11.10 El Capitan. If you are installing on 10.10 or earlier, previous VFX Forth files in /usr/bin will be removed.

The installer script should have created a short cut for you, vfxosx.

The support library, vfxsupp.1.dylib, extends the number handler to search for Mac OS X constants that are then treated as if their value had been entered numerically. The search is case sensitive, and yes we have seen constants which differ only in case and return different values. This library avoids having to keep a huge number of constant definitions in the Forth dictionary. The support library is only needed for development, and may not be shipped with applications.

Installing from the tarball

The tarball was created with

 tar cvfz ...

Extract the tarball to a suitable directory.

 tar xvfz ...

View, edit if necessary, and then run the supplied script InstallMe.Osx32.sh.

The executables and shared libraries are in the Bin subdirectory. You should now copy these to the "right" places, /usr/bin and /usr/lib. The files to copy to /usr/bin are vfxosx and skimpage.scpt. The files to copy to /usr/lib are libmpeparser.0.dylib and vfxsupp.1.0.1.dylib. This last needs a symbolic link as vfxsupp.1.dylib.

  ln -s vfxsupp.1.0.1.dylib vfxsupp.1.dylib

The shared library libmpeparser.0.dylib contains the code to support persistent INI files and and vfxsupp.1.0.1.dylib contains a large number of (case-sensitive) constants from Mac OS X header files.

Getting started

If you do not know Forth, the downloads contain a PDF version of "Programming Forth" by Stephen Pelc. You can also obtain the same PDF file from the MPE website.

Books on Forth are available from MPE and others. For more details see:

  http://www.mpeforth.com/books.htm

Do not be afraid to play. Forth is an interactive system designed to help you explore its own programming environment. There is plenty of source code in the Examples and Lib directories, so look at it, edit it, and see what happens!

Configuration

Set up your editor19<q

VFX Forth for Mac OS X is not supplied with an editor. If you want to set one, use:

  editor-is <editor>
  editor-is /Applications/TextWrangler.app/Contents/MacOS/TextWrangler
  editor-is /Applications/UltraEdit.app/Contents/MacOS/UltraEdit
  editor-is /bin/vi
  editor-is emacs

The word editor-is needs a Unix command line path to the executable. If your editor is installed as a bundle, you can usually find the executable file as follows using TextWrangler as an example. Finder will usually show it in

  Applications/TextWrangler

which is really a special directory called

  Applications/TextWrangler.app

The executable file is usually in a subfolder called

  Contents/MacOS

which gives the full path

  /Applications/TextWrangler.app/Contents/MacOS/TextWrangler

A much easier and more reliable way to construct a path name is to use the tool "Find Any File" from the App Store. If you enter TextWrangler as the name to search for, look for the result labelled "Unix Executable File", select it, right click in the bottom status bar and you can then copy it into your editor or into the VFX console.

SetLocate tells VFX Forth how your editor can be called to go a particular file and line. Use in the form:

  SetLocate  <rest of line>

where the text after SetLocate is used to define how parameters are passed to the editor, e.g. for Emacs, use:

  SetLocate    +%l% "%f%" &

  EMACS
    editor-is emacs
    SetLocate +%l% "%f%"
              --no-wait +%l% "%f%"
  TextWrangler (download command line tools)
    editor-is edit
    SetLocate +%l% "%f%" &
  UltraEdit
    editor-is /Applications/UltraEdit.app/Contents/MacOS/UltraEdit
    SetLocate -- "%f%" --lc%l%:1

Note that UltraEdit requires you not to add the trailing '&'. In most cases it is needed, but you will have to try it to find out.

Thanks to Charles Curley for the additional EMACs information. See http://www.charlescurley.com. He also notes that you should add the following to your .emacs file:


 (if (or (string-equal system-type "gnu/linux")
         (string-equal system-type "cygwin"))
     (server-start)
          (message "emacsserver started."))

It is essential to place the quote marks around the %f% macro if your source paths include spaces.

For LOCATE and other source code tools to work, VFX Forth must know where its source code is. The root of the source code directory is saved in the VFXPATH text macro, which is expanded when needed. To see what the current setting is, use:

  ShowMacros

To see how the macro is used, look at the source file list:

  .Sources

To set the macro, use something like

   c" /Users/stephen/VfxForth" setMacro VfxPath

If you are going to use the Cocoa interface, you may also need to set the BasePath macro:

   c" /Users/stephen/VfxForth" setMacro BasePath

For more information on text macros, see the chapter on "Text macro substitution".

Set up the PDF help system

For words for which you do not have the source, but are documented in the manual, you can use HELP <name>, e.g.

  help help

This needs configuration according to which PDF viewer and version you are using.

The default incantations are for xpdf.


 s" xpdf %h%.pdf %p% &" HelpCmd$ place
 s" %LOAD_PATH%/../doc/VfxOsx" HelpBase$ place
 #17 HelpPage0 !

The first line tells the system how to run a PDF viewer so that it displays the page %p%. The second line defines the PDF file base name, which is used to find the PDF file and its associated index file. The third line defines the page offset from the start of the PDF file to page number 1, i.e. to step over the table of contents and so on.

The default PDF viewer for Mac OS X is Preview. It can be run from the command line using:

  open -a Preview filename.pdf

however, going to a page number is undocumented. The best solution we have found is to install the Skim package from:

  http://skim-app.sourceforge.net/

This can be run using the supplied executable script skimpage.scpt. Copy the script file from the VFX Bin directory to a suitable directory such as /usr/bin in the usual executable path. The script will be run in the form:

  skimpage.scpt "<file>" <pageno>

A suitable setup for VFX Forth is:

  s\" skimpage.scpt \q%h%.pdf\q %p%" HelpCmd$ place
  s" /Users/<name>/VfxForth/PDFs/VfxOsx" HelpBase$ place
  #14 HelpPage0 !

The configuration information is preserved between sessions in a configuration file, by default ~/.VfxForth.ini.

New features in this version

Changes between versions are documented in reverse chronological order in the file <VFX>/Doc/Release.vfx.txt, which is available from the Help menu in the Windows version. The file contains the changes for all versions.

The major changes in v5.1 are interpreter changes:

  1. to support the NDCS model (non-default compilation semantics) described in the paper by Stephen Pelc at EuroForth 2017. See PDF paper.
  2. to add recognisers to the interpreter. Recognisers consist of tables of parsing words which recognise particular features of Forth such as words, integers, floating point number, and dot parsers for ClassVFX and CIAO. Recognisers are currently being standardised by the Forth 202x committee, and the details should be regarded as subject to change.

The additional words are described in the paper and the changes to the Forth text interpreter can be seen in the file Kernel/Common/kernel.fth. The main changes are the introduction of three words:

In practice, these changes have almost no impact on normal Forth programming. However, if you want to explore words that have different actions during compilation and interpretation, these changes are important.

Acknowledgements

The following people have gone out of their way in the production of VFX Forth for Mac OS X.