| 1 | Overview |
| 2 | ======== |
| 3 | |
| 4 | TODO: |
| 5 | |
| 6 | - Explain `ned_programs` folder |
| 7 | |
| 8 | - Mention machine specs unique to NEDsim screensaver (64k element stack, 64MB heap, etc) |
| 9 | |
| 10 | - General description of NED (32-bit RISC stack machine, syllable packed words, etc) |
| 11 | |
| 12 | - Screenshots of operation |
| 13 | |
| 14 | - Link to main NED1 repository for full simulator |
| 15 | |
| 16 | Status |
| 17 | ====== |
| 18 | |
| 19 | Complete. Tested on FreeBSD. |
| 20 | |
| 21 | |
| 22 | Instructions |
| 23 | ============ |
| 24 | |
| 25 | The included `Makefile` includes targets for `make all` to build the hack, |
| 26 | `make clean` to delete any build detritus, and `make run` to execute the hack. |
| 27 | |
| 28 | If you are running on FreeBSD, simply run one of those three commands. Anywhere |
| 29 | else, edit the `Makefile` to suit your environment per the comments included in |
| 30 | that file. Note that the `Makefile` assumes a copy of the screenhack library |
| 31 | source code is located at `../screenhack/` relative to this directory. |
| 32 | |
| 33 | For assistance setting `$(DEFINES)` in the `Makefile` on non-FreeBSD platforms, |
| 34 | consider downloading the XScreensaver source tarball, running `./configure` in |
| 35 | the unpacked directory, and examining the resulting `config.h` file. |
| 36 | |
| 37 | Although NEDsim can integrate with XScreensaver, the presence of XScreensaver |
| 38 | is not strictly required. NEDsim will both build and execute using only the |
| 39 | included screenhack library. |
| 40 | |
| 41 | |
| 42 | Command-Line Flags |
| 43 | ================== |
| 44 | |
| 45 | The following CLI flags customize the operation of NEDsim at runtime. |
| 46 | |
| 47 | - **`-delay N`**: Request `N` millisecond delay between each frame of NEDsim, |
| 48 | itself equivalent to one clock cycle of the simulation. Note that this is |
| 49 | only a request; XScreensaver reserves the right to ignore requested values, |
| 50 | and of course we execute at the mercy of the kernel's scheduling. In |
| 51 | practice, non-absurd values are reasonably well respected. |
| 52 | |
| 53 | - **`-color N`**: Select color scheme `N` from `color_list[]` in `NEDsim.c`. |
| 54 | |
| 55 | - **`-binary FILENAME`**: Instruct NEDsim to execute `FILENAME`, a NED1 a.out |
| 56 | format executable file. If this option is not specified, one of the NED1 |
| 57 | programs embedded directly in NEDsim will be chosen at random. |
| 58 | |
| 59 | - **`-heapwindow N`**: Instruct NEDsim to located the window into RAM at |
| 60 | address `N`. Note that allowable values depend upon the quantity of |
| 61 | simulated RAM and must take into account the size of the heap window, |
| 62 | itself dependent upon the size of your display. Also note that this CLI |
| 63 | option is ignored unless the `-binary FILENAME` option was passed. |
| 64 | |
| 65 | |
| 66 | XScreensaver Integration |
| 67 | ======================== |
| 68 | |
| 69 | In addition to running as a standalone program, NEDsim can be integrated into |
| 70 | the XScreensaver framework. |
| 71 | |
| 72 | To accomplish this integration, begin by installing and configuring |
| 73 | XScreensaver via whatever method is appropriate for your operating system. The |
| 74 | following instructions assume the filesystem paths used by FreeBSD packages and |
| 75 | ports; your paths may differ. After XScreensaver installation, ensure all |
| 76 | pertinent config files are created by running `xscreensaver-demo` and |
| 77 | configuring XScreensaver for your system. |
| 78 | |
| 79 | After XScreensaver is configured and working on your system, ensure that NEDsim |
| 80 | runs in standalone mode on your system. If you can `make clean run` in the |
| 81 | `screensavers/hacks/NEDsim/` folder and see the hack's visual output, you're |
| 82 | ready to move on. |
| 83 | |
| 84 | At this point, copy the hack into your XScreensaver hack directory. For |
| 85 | example, with prerequisite steps spelled out: |
| 86 | |
| 87 | git clone git://git.subgeniuskitty.com/screensavers |
| 88 | cd screensavers/hacks/NEDsim |
| 89 | make clean all |
| 90 | cp NEDsim /usr/local/bin/xscreensaver-hacks/nedsim |
| 91 | |
| 92 | Now create the file `nedsim.xml` wherever your system stores XScreensaver |
| 93 | config files and populate it with the contents shown below. For example, on |
| 94 | FreeBSD: |
| 95 | |
| 96 | vi /usr/local/share/xscreensaver/config/nedsim.xml |
| 97 | |
| 98 | <?xml version="1.0" encoding="ISO-8859-1"?> |
| 99 | |
| 100 | <screensaver name="nedsim" _label="NEDsim"> |
| 101 | |
| 102 | <command arg="-root"/> |
| 103 | |
| 104 | <string id="delay" _label="Delay (msec):" arg="-delay %" /> |
| 105 | <string id="color" _label="Color index (int):" arg="-color %" /> |
| 106 | <string id="binary" _label="NED1 a.out executable (filename):" arg="-binary %" /> |
| 107 | <string id="heapwindow" _label="Heap window start address (int):" arg="-heapwindow %" /> |
| 108 | |
| 109 | <_description> |
| 110 | NEDsim simulates a blinkenlight front panel for a 32-bit RISC stack machine |
| 111 | architecture named NED. See http://subgeniuskitty.com for more information. |
| 112 | </_description> |
| 113 | </screensaver> |
| 114 | |
| 115 | The next step integrates NEDsim into an individual user's XScreensaver config |
| 116 | via the file `~/.xscreensaver`. If preferred, it could instead be done in the |
| 117 | global XScreensaver config. |
| 118 | |
| 119 | In the `~/.xscreensaver` file, create a NEDsim entry under the `programs:` |
| 120 | label in the same list as all the other hacks. Position in the list is |
| 121 | irrelevant, but ensure you don't paste NEDsim's entry into the middle of |
| 122 | pre-existing, multi-line entries. For context, the example below includes a |
| 123 | multi-line entry, a GL entry and a plain entry. All that is needed is to insert |
| 124 | the NEDsim line somewhere in the `programs:` list, as demonstrated. |
| 125 | |
| 126 | vi ~/.xscreensaver |
| 127 | |
| 128 | <snip> |
| 129 | programs: \ |
| 130 | xplanet -vroot -wait 1 -timewarp 400 \ |
| 131 | -label -origin moon \n\ |
| 132 | GL: fireflies -root \n\ |
| 133 | nedsim -root \n\ |
| 134 | blitspin -root \n\ |
| 135 | <snip> |
| 136 | |
| 137 | That's all. Now you can run `xscreensaver-demo` and select NEDsim just like any |
| 138 | other hack. |
| 139 | |