--- /dev/null
+Overview
+========
+
+TODO:
+
+ - Explain `ned_programs` folder
+
+ - Mention machine specs unique to NEDsim screensaver (64k element stack, 64MB heap, etc)
+
+ - General description of NED (32-bit RISC stack machine, syllable packed words, etc)
+
+ - Screenshots of operation
+
+ - Link to main NED1 repository for full simulator
+
+Status
+======
+
+Complete. Tested on FreeBSD.
+
+
+Instructions
+============
+
+The included `Makefile` includes targets for `make all` to build the hack,
+`make clean` to delete any build detritus, and `make run` to execute the hack.
+
+If you are running on FreeBSD, simply run one of those three commands. Anywhere
+else, edit the `Makefile` to suit your environment per the comments included in
+that file. Note that the `Makefile` assumes a copy of the screenhack library
+source code is located at `../screenhack/` relative to this directory.
+
+For assistance setting `$(DEFINES)` in the `Makefile` on non-FreeBSD platforms,
+consider downloading the XScreensaver source tarball, running `./configure` in
+the unpacked directory, and examining the resulting `config.h` file.
+
+Although NEDsim can integrate with XScreensaver, the presence of XScreensaver
+is not strictly required. NEDsim will both build and execute using only the
+included screenhack library.
+
+
+Command-Line Flags
+==================
+
+The following CLI flags customize the operation of NEDsim at runtime.
+
+ - **`-delay N`**: Request `N` millisecond delay between each frame of NEDsim,
+ itself equivalent to one clock cycle of the simulation. Note that this is
+ only a request; XScreensaver reserves the right to ignore requested values,
+ and of course we execute at the mercy of the kernel's scheduling. In
+ practice, non-absurd values are reasonably well respected.
+
+ - **`-color N`**: Select color scheme `N` from `color_list[]` in `NEDsim.c`.
+
+ - **`-binary FILENAME`**: Instruct NEDsim to execute `FILENAME`, a NED1 a.out
+ format executable file. If this option is not specified, one of the NED1
+ programs embedded directly in NEDsim will be chosen at random.
+
+ - **`-heapwindow N`**: Instruct NEDsim to located the window into RAM at
+ address `N`. Note that allowable values depend upon the quantity of
+ simulated RAM and must take into account the size of the heap window,
+ itself dependent upon the size of your display. Also note that this CLI
+ option is ignored unless the `-binary FILENAME` option was passed.
+
+
+XScreensaver Integration
+========================
+
+In addition to running as a standalone program, NEDsim can be integrated into
+the XScreensaver framework.
+
+To accomplish this integration, begin by installing and configuring
+XScreensaver via whatever method is appropriate for your operating system. The
+following instructions assume the filesystem paths used by FreeBSD packages and
+ports; your paths may differ. After XScreensaver installation, ensure all
+pertinent config files are created by running `xscreensaver-demo` and
+configuring XScreensaver for your system.
+
+After XScreensaver is configured and working on your system, ensure that NEDsim
+runs in standalone mode on your system. If you can `make clean run` in the
+`screensavers/hacks/NEDsim/` folder and see the hack's visual output, you're
+ready to move on.
+
+At this point, copy the hack into your XScreensaver hack directory. For
+example, with prerequisite steps spelled out:
+
+ git clone git://git.subgeniuskitty.com/screensavers
+ cd screensavers/hacks/NEDsim
+ make clean all
+ cp NEDsim /usr/local/bin/xscreensaver-hacks/nedsim
+
+Now create the file `nedsim.xml` wherever your system stores XScreensaver
+config files and populate it with the contents shown below. For example, on
+FreeBSD:
+
+ vi /usr/local/share/xscreensaver/config/nedsim.xml
+
+ <?xml version="1.0" encoding="ISO-8859-1"?>
+
+ <screensaver name="nedsim" _label="NEDsim">
+
+ <command arg="-root"/>
+
+ <string id="delay" _label="Delay (msec):" arg="-delay %" />
+ <string id="color" _label="Color index (int):" arg="-color %" />
+ <string id="binary" _label="NED1 a.out executable (filename):" arg="-binary %" />
+ <string id="heapwindow" _label="Heap window start address (int):" arg="-heapwindow %" />
+
+ <_description>
+ NEDsim simulates a blinkenlight front panel for a 32-bit RISC stack machine
+ architecture named NED. See http://subgeniuskitty.com for more information.
+ </_description>
+ </screensaver>
+
+The next step integrates NEDsim into an individual user's XScreensaver config
+via the file `~/.xscreensaver`. If preferred, it could instead be done in the
+global XScreensaver config.
+
+In the `~/.xscreensaver` file, create a NEDsim entry under the `programs:`
+label in the same list as all the other hacks. Position in the list is
+irrelevant, but ensure you don't paste NEDsim's entry into the middle of
+pre-existing, multi-line entries. For context, the example below includes a
+multi-line entry, a GL entry and a plain entry. All that is needed is to insert
+the NEDsim line somewhere in the `programs:` list, as demonstrated.
+
+ vi ~/.xscreensaver
+
+ <snip>
+ programs: \
+ xplanet -vroot -wait 1 -timewarp 400 \
+ -label -origin moon \n\
+ GL: fireflies -root \n\
+ nedsim -root \n\
+ blitspin -root \n\
+ <snip>
+
+That's all. Now you can run `xscreensaver-demo` and select NEDsim just like any
+other hack.
+
projects / screensavers / commitdiff