Initial commit of README for NEDsim. Still lacks an Overview section.

[screensavers] / hacks / NEDsim / README.md

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.