The source code for documentation and this website is managed as a Mercurial repository on BitBucket. Each official Haystack version is packaged as a self contained zip file which can be downloaded from the Downloads tab. Each build file provides:
- source code for all documentation and tag definitions
- ability to run website locally
- build script to rebuild docs from source
Source code and build scripts are written in the Fantom programming language. You will need a Java VM installed to run the website locally or rebuild from source. Once a build is download, the easiest way to run is by calling the
bin/fan launch script.
// cd to the dir where you installed the build cd ~/haystack-2.0.9/ // to run website on your local machine bin/fan haystackws // run on a port other than 8080 bin/fan haystackws -port 8081 // rebuild from source bin/fan src/build.fan
See Fantom Setup Docs for more information on setting up and trouble shooting your Fantom environment.
Builds are organized with the following directory structure:
bin/ // launch scripts etc/ // config files, unit/tz databases lib/ // runtime modules fan/ // Fantom pod files java/ // Java runtime for Fantom src/ // top level dir for source code build.fan // top level build script haystackws/ // source code for the haystackws pod docs/ // chapter source in fandoc format equips/ // equip points in plain text fan/ // Fantom source code for website locale/ // localized translations of tags res/ // CSS, image resource files tags/ // tag definitions in Trio format
The website itself and all the documentation is primarily sourced into a single pod named
haystackws. The website is built upon the Fantom runtime and a web framework nicknamed sidewalk. These dependencies are included in binary form in
The overall design of the website is as follows:
Main: bootstrap code which loads library and launches web service
HaystackLoader: loads source docs and tags and compiles into
Html: suite of renderers used by loader to generate HTML
Lib: set of immutable data structures and HTML for compiled docs and tags
Documentation is written as plain text formatted as fandoc.
Fandoc hyperlinks are used liberally. The following link formats are supported:
point: link to a tag
- TagModel: link to a chapter
- TagModel#tagKinds: link to a chapter with specific fragment anchor id
Tag definitions are plain text formatted as Trio files. Each tag is itself defined as a set of tags:
tag: programmatic name of the tag
kind: value type of tag or "Obj" if multiple value types are supported
doc: documentation formatted as fandoc
docInclude: chapter name with optional fragment id to include into tag documentation
alsoSee: optional set of comma separated tag names
usedWith: optional set of comma separated tag names
Here is an example for
tag: maxVal kind: Number alsoSee: minVal, curVal usedWith: point docInclude: Structure#pointMinMax doc: Applied to `point` to define the maximum value to read from a sensor or to write from a command/setpoint. This value's unit must match the point's `unit` tag.