Programming largely consists of a repeating iteration of Editing, Compiling, and Running programs (with occasional breaks for snacks). The following overview and tips should help you get started on the A-Shell version of this timeless activity.
Editors
Although you can use any text or program editor you like, most A-Shell programmers use one or both of the following:
VUE is an old-school full-screen plain text editor, vaguely similar to the famous UNIX editor vi. Its strong points are that it is:
• built in to A-Shell, which means it can be launched from the dot prompt or via a subroutine within a program
• available as a standalone executable in the UNIX environment
• platform independent
• very fast and responsive if you know the keyboard commands
A-Shell Programmer's Notepad ("APN") is a modern Windows program editor / IDE ("Integrated Development Environment"), similar to other IDEs such as Visual Studio. Its strong points are:
• follows typical Windows conventions so will be instantly familiar to most programmers experienced with other Windows editors
• multi-file, multi-window
• understands ASB syntax and A-Shell directory structure so is able to recognize/locate/open ++INCLUDE files
• integrated compiler: click on errors in the output window to jump directly to the file/line for editing
• can be extended with scripts written in Python
• supports workspaces and projects
• syntax highlighting, call tips, code completion, undo/redo
Compilers
The ASB compiler processes your source code (typically with a .BAS or .BP extension), creating a run module (typically with a RUN, LIT, or SBX extension, depending on the intended use). There is really only one compiler, but it is packaged in a number of forms to match your working style:
From the A-Shell dot prompt:
• COMPIL.LIT, e.g. .COMPIL MYPROG/M/I/X:2
• COMPLP.LIT - variation (supporting the AMOS BASICPlus) that assumes .BP file extension, /X:1
• OCMPIL.LIT - variation (supporting the original AMOS BASIC 1.3) that assumes /13
From within a program (if you want to create your own compilation wrapper), you can invoke the compiler using:
XCALL MIAMEX, MX_COMPIL, filename, switches, ...
From the Windows shell prompt:
>COMPIL.EXE <switches> <program>
(The compil.exe package is also used by APN for integrated ASB compilation.)
From the UNIX shell prompt:
$ compil <switches> <program>
Execution
There are three forms of compiled programs, identified by the file extension. All have essentially the same internal format but are executed in different ways:
• RUN modules (e.g. PROG.RUN) are executed using the RUN command from a dot prompt or from within a CMD or DO file, e.g. (RUN PROG)
• SBX modules (e.g. PROG.SBX) act as subroutines and are called from within another program using the subroutine statement. See Subroutines vs. Programs for details on differences between SBX and RUN modules.
• LIT modules (e.g. PROG.LIT) act as system commands and are executed from the dot prompt, or from within a CMD or DO file, by specifying just the module name.
All three have the same fundamental structure; the file extension determines the usage and behavior. You can use COPY or RENAME to convert from one type to another, or use the FORCE_FSPEC ++pragma within the source code to instruct the compiler how to name the compile program directly.
A running program can also launch another LIT or RUN program, either as a subroutine using XCALL AMOS, or by chaining to it using the CHAIN statement.
Examples
RUN modules from the dot prompt or a CMD or DO file:
.RUN MYPROG
.RUN DSK2:MYPROG.RUN[100,2]
LIT modules from the dot prompt or a CMD or DO file (see Command Search Path) :
.LOG SYS: ; LOG.LIT
.DIR/W ; DIR.LIT
.TEST.LIT ; TEST.LIT
From within a program:
XCALL FOOBAR,1,2 ! call FOOBAR.SBX; search [p,pn], [p,0], DSK0:[7,6]
CHAIN "INVOIC" ! link to INVOIC.RUN; search [p,pn], [p,0], DSK0:[7,6]
XCALL AMOS,"RUN TEST" ! execute TEST.RUN as subroutine