Homespun Spin Compiler - rosco-pc/propeller-wiki GitHub Wiki

Homespun is a command-line Spin compiler that reads .spin files and outputs .eeprom files. It is written in C# and runs on Windows with the .Net framework and on Linux with Mono.

Homespun is a personal project and not a professional product. Use Homespun at your own risk.

Download the executable here: Propeller forum thread.
(Check the thread's end too for smashed old bugs and not yet merged PRs and resulting updated binaries. — 20200407, yeti)

In my testing, Homespun generates output that is identical to Proptool's (except the occasional least-significant bit in floating-point constants), which was my original goal. Now I'm using Homespun as a testbed to try out extensions to the compiler and the language. All information here is subject to change as Homespun continues to evolve.

Installation consists simply of copying homespunXXX.exe (where XXX is the version number) to your Windows (or Linux) machine. As long as you have the .Net framework (or Mono) installed, Homespun should run.

There are two ways of running homespun. One is directly from a terminal using wine homespunXXX [options] <filename.spin>. The other one is using a wine terminal, for this the command has to be mono homespunXXX.exe [options] <filename.spin>. This seems to be a limitation of mono (at least in the 1.9.1 and 2.2 versions).

There is no wine executable that you can easily call (and I'm aware of) from the Mac OS X terminal. So the way to get homespun to run is to use a Darwine terminal settings file. This file is a settings file for the Mac OS X terminal that will launch the command line interpreter in darwine (located in /Applications/Darwine/Wine.bundle/Contents/bin/wine). From this command line the path to the mono executable can be added, but it must be done every time:

set path=C:\Program Files\Mono-2.2\bin;%PATH%

A more permanent way is to add it to the registry in HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session Manager\Environment\PATH

PATH=C:\windows\system32;C:\windows;C:\Program Files\Mono-2.2\bin

Every time you launch the new terminal properties file this path will be set so you can launch homespunXXX.exe [options] <filename.spin>. This seems to be a limitation of mono (at least in the 2.2 version I tested under darwine).

At a command prompt, type "homespunXXX filename.spin". You can omit the ".spin"; Homespun will add it. The program will compile the Spin source code and produce a file called filename.eeprom (or filename.binary).

You may specify command-line options and the filename in any order. Options begin with "-".

• -b - generates a .binary file instead of the default .eeprom file.
• -c - generates a .dat file containing the top object's DAT data.
• -d - produces a listing file, including disassembled Spin bytecode.
• -D - define a symbol (as in #define); e.g. -D DEBUG
• -in - controls informational messages: -i0 suppresses all messages, -i2 and -i3 show some messages, -i3 shows all messages.
• -L - specify library path. See below for more information.
• -w - enables warnings for common coding pitfalls -- code that is syntactically correct but perhaps does something other than what you intended. See below for more information.
• -sob - generates a .sob file for every .spin file compiled.

Details to come. Or maybe not. Is anybody reading this? Email me if you're interested.

If the -w option is specified, Homespun will generate a warning when it encounters the following potentially problematic code:

• JMP/DJNZ/etc without #
• RES without a count
• ORG without an address
• data after RES
• COGNEW containing a call to another object
• data truncation (e.g. DAT BYTE 1000)

Filenames in OBJ declarations and FILE directives can contain ":" and "" (and "/"), so you can hardcode full paths. However, a more flexible approach is to use the -L option and the SPINLIB environment variable. Invoke Homespun using -L to specify directories (one -L per directory). For example,

Homespun028 -L \second\ -L ..\third\ first\blah.spin

If your input filename contains a directory, as in this example, that directory is searched first. If you just supply the input filename, the current directory is searched first.

In this example, Homespun will search for blah.spin first in first, then in \second, then ..\third. Homespun will search those same directories for any objects referenced in blah.spin. (Note: Homespun will supply the trailing "" if necessary. It will also switch to "/" on non-Windows systems, but to be on the safe side, add the final separator yourself.)

You can also set the SPINLIB environment variable to specify additional directories:

set spinlib=c:\fourth\;\Program Files\Parallax Inc\Propeller Tool v1.05.5

The /L option takes precedence over SPINLIB, so if we invoke Homespun with the same command line as before, the search order will be

• first
• \second\
• ..\third\
• c:\fourth\
• \Program Files\Parallax Inc\Propeller Tool v1.05.5\

VAR variables can now be multidimensional arrays (any number of dimensions).

VAR byte myArray[2,40,13] ' a 2x40x13 array

... in a PUB or PRI:
  myArray[i,j,k] := blah

No bounds-checking is performed.

You can include a file inside another file using #include. Example:

#include "defs.h"

Homespun will search the library paths for the file.

Homespun supports the following conditional compilation directives:

• #ifdef symbol
• #elseifdef symbol
• #else
• #endif
• #ifndef

#ifdef and #elseifdef check to see if symbol has been defined using #define (see below). Example:

#define HYDRA
CON
#ifdef HYDRA
  _clkmode = xtal1 + pll8x
  _xinfreq = 10_000_000
#elseifdef HYBRID
  _clkmode = xtal1 + pll16x
  _xinfreq = 6_000_000
#else
  _clkmode = xtal1 + pll16x
  _xinfreq = 5_000_000
#endif

#ifndef MYDEF
#define MYDEF
#endif

You can do simple text substitution using #define. The syntax of the #define directive is:

#define <symbol> <replacement-text>

is whatever text follows on that line. Any identifier tokens in the source file that match will be replaced with . Matching is case-insensitive. For example:

#ifdef PropII
#define ADDR LONG
#else
#define ADDR WORD
#endif

var addr baseaddress ' replaces addr with long or word, but doesn't touch the "addr" in baseaddress.

Note that the scope of a #defined symbol is from the #define to the end of the file. Like BST, Homespun passes #defined symbols down to sub-objects (provided the #define precedes the OBJ section).

Also note that all #-directives must start in column 1.

Homespun can reserve space in low hub memory (starting at $0010). Declare "CON _SPACE = xxx" where xxx is the number of bytes you want to reserve. Homespun totals up the _SPACE constants in all the objects in your program.

@@@datSymbol evaluates at compile time to the absolute hub address of datSymbol. datSymbol must be defined in a DAT section.

• -d listing is incorrect if _SPACE is in effect.
• RESULT keyword is not handled correctly.

• Make error messages less cryptic
• Clean up and release source code (a long way off)

Homespun is a work in progress. Feel free to contact me to report bugs or to suggest improvements. Many thanks to those who already have done so.

Michael Park (mp__-at-hotmail.com) Edit Feb 26, 2011 by Jazzed

Homesoun sources: https://github.com/ZiCog/HomeSpun