From: Aaron Taylor Date: Mon, 12 Jul 2021 22:36:40 +0000 (-0700) Subject: Initial commit of README for NEDsim. Still lacks an Overview section. X-Git-Url: http://git.subgeniuskitty.com/screensavers/.git/commitdiff_plain/d654a58ee818e13a9ee507c1905c6d2cd475216c Initial commit of README for NEDsim. Still lacks an Overview section. --- diff --git a/hacks/NEDsim/README.md b/hacks/NEDsim/README.md new file mode 100644 index 0000000..9216e51 --- /dev/null +++ b/hacks/NEDsim/README.md @@ -0,0 +1,139 @@ +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 + + + + + + + + + + + + + <_description> + NEDsim simulates a blinkenlight front panel for a 32-bit RISC stack machine + architecture named NED. See http://subgeniuskitty.com for more information. + + + +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 + + + programs: \ + xplanet -vroot -wait 1 -timewarp 400 \ + -label -origin moon \n\ + GL: fireflies -root \n\ + nedsim -root \n\ + blitspin -root \n\ + + +That's all. Now you can run `xscreensaver-demo` and select NEDsim just like any +other hack. +