This section provides a general overview of SwiftForth, including information necessary to help you install the system and to become familiar with its principal features.
On This Page
1.1 Components of SwiftForth
SwiftForth consists of the following components:
- Executable image of the SwiftForth development system, including the Interactive Development Environment (IDE), host OS interface functions, assembler, disassembler, and other programming tools.
- The evaluation version includes source for all options and examples.
- The licensed version adds source for the entire SwiftForth system, including the cross compiler that allows advanced programmers to modify the underlying system.
- Online documentation
The SwiftForth directory structure is shown below. The evaluation version does not include the console, kernel, or xcomp directories (the source for the debug window, kernel, and cross compiler).
***SwiftForth directory structure
1.2 SwiftForth System Requirements
These are the OS-specific requirements for SwiftForth:
- GUI IDE for WIndows systems: Windows 10 or later
- CLI IDE for macOS systems: macOS 10.15 (Catalina) or later
- CLI IDE for Linux systems: Linux kernel 6.0 or later
You will also need a programmer’s editor of your choice. Provision is made for linking interactive features of SwiftForth with most standard editors.
1.3 Installation Instructions
This section describes how to install and run your SwiftForth development system. It also describes basic procedures for compiling and testing programs, including the demos and sample code provided with your system.
1.3.1 Installing SwiftForth
SwiftForth for Windows, Linux, and macOS are supplied via download only. If you have a licensed version, you will receive the download links via email. If you’re using the evaluation version, download from the Evaluation Downloads page. Follow the installation instructions on the download page.
1.3.2 Linking to a Text Editor
The SwiftForth Interactive Development Environment (IDE) contains a number of programmer aids that are facilitated by a link to a text editor. The default editor for Windows systems is Notepad; alternatively, you may configure SwiftForth to use an editor of your choice by specifying certain command formats.
1.4 Development Procedures
Here we provide a brief overview of some development paths you might pursue. You may wish to:
- Run sample programs installed with your system.
- Write and test application routines.
- Prepare a custom image of your SwiftForth system with added routines.
Guidelines for doing these things are given in the following sections. Further details about SwiftForth’s interactive development tools are given in Section 2.
1.4.1 Exploring SwiftForth
Launch SwiftForth from the Start menu or by double-clicking the sf.exe icon. The main window SwiftForth presents is called the command window. Within this window, SwiftForth will attempt to execute everything you type. You may also use your mouse to select words and to perform other functions. The command window is described in Section 2.3.1.
When you type in the command window, SwiftForth will wait to process what you’ve typed until you press the Enter key. Before pressing Enter, you may backspace or use the left- and right-arrow keys to edit your command line. The up- and down-arrow keys page through previous command lines.
Forth commands are strings separated by spaces. The default behavior of SwiftForth is to be case-insensitive; that is, it treats upper-case and lower-case letters the same. For consistency, we will use upper case for most SwiftForth words. Windows calls, however, are case-sensitive, and are spelled with mixed case following standard Windows nomenclature; these words should always be spelled exactly as shown. For this reason, SwiftForth compiles all word names preserving their original case. You may temporarily set SwiftForth to be case-sensitive by using the command CASE-SENSITIVE, and return to case-insensitivity by using the command CASE-INSENSITIVE; however, we do not recommend operating for extended periods in CASE-SENSITIVE mode, as aspects of the object system (Section 10) may not function properly in this mode.
If you are new to the Forth programming language, we recommend you start your exploration by looking at some of the sample programs provided with the system. These range from simple functions to moderately complex games with simple graphics and sound. These are described in Section 1.4.2. As you look at the source for these applications in your editor, you may go to the SwiftForth command window to use LOCATE to find the source for words that are not part of the application file; the manuals provided with this system provide discussion of generic Forth words.
If you are an experienced Forth programmer, you will also benefit from looking at the sample programs to see how SwiftForth performs Windows-specific functions. You may also wish to LOCATE various low-level words to familiarize yourself with this implementation, which is discussed in Section 5.
References
LOCATE, Section 2.4.1
1.4.2 Running the Sample Programs
SwiftForth ships with a number of sample programs. These may be found in the Swiftforth\lib\samples directory. All are provided as source files that you may INCLUDE and may be run according to their instructions. Many may be loaded from the dialog box invoked by the Tools > Optional Packages > Generic Samples or Win32 Samples menu items.
References
INCLUDE (loading source files), Section 3.1
Tools menu selections, Section 2.3.5
1.4.3 Developing and Testing New Software
You may add new definitions to SwiftForth in four ways:
Type them directly from the keyboard in the command window.
Copy them from a source file and paste them into the command window (you can also copy definitions from the command window or keyboard history window and paste them into files).
Interpret an entire source file using the File > Include menu option, or by typing INCLUDE .
Load them from Forth blocks, if the block-handling options are loaded.
The first two are extremely convenient for exploring a problem and for testing new ideas. Later stages of development generally involve editing a file and repeatedly loading it using INCLUDE. However, to maximize your debugging efficiency, remember to keep your definitions short (typically a few lines) and always follow the practice of bottom-up testing of individual, low-level words before trying the higher-level functions that depend on them.
References
Source in text files, Section 3.1
Source in Forth blocks, Section A.1
Keyboard history window, Section 2.4.8
1.5 Licensing Issues
When you install SwiftForth, the installation process obtains your consent to a license agreement describing the terms under which you may use this product. You may find a copy of this license agreement in SwiftForth\doc\license.rtf.
SwiftForth is an unusual product, in that it is a development environment that can also produce program images containing the development environment itself. In this regard, SwiftForth differs dramatically from development systems such as Visual Basic which only produce executables. Because of this, we want to be very clear as to what is and is not permitted under this license.
1.5.1 Use of the Runtime Kernel
The purpose of SwiftForth is to enable you to develop Windows applications. Your applications may incorporate the SwiftForth run-time kernel as a component of a turnkey application in which the compiler and assembler or other programming aids are not available to any user of the application software. If you need distribution rights other than these, please contact FORTH, Inc.
1.5.2 Use of the SwiftForth Development System
This section describes how you may use the SwiftForth development environment. You may:
- use the SwiftForth development system on any single computer;
- use the SwiftForth development system on a network, provided that each person accessing the Software through the network must have a copy licensed to that person;
- use the SwiftForth development system on a second computer as long as only one copy is used at a time;
- copy SwiftForth for archival purposes, provided that any copy must contain all of the original Software’s proprietary notices; or
distribute the run-time kernel provided with this system in accordance with the terms described in Use of the Runtime Kernel above. - If you have purchased licenses for multiple copies of SwiftForth, all copies must contain all of the original Software’s proprietary notices. The number of copies is the total number of copies that may be made for all platforms.
You may not:
- permit other individuals to use the SwiftForth development system except under the terms listed in Use of the Runtime Kernel above;
- permit concurrent use of the SwiftForth development system;
- modify, translate, reverse-engineer, or create derivative works based on the SwiftForth development system except as provided in Use of the Runtime Kernel above;
- copy the Software other than as specified above;
- rent, lease, grant a security interest in, or otherwise transfer rights to the Software without first obtaining written permission from FORTH, Inc.; or
- remove any proprietary notices or labels on the Software.