Commit | Line | Data |
---|---|---|
d654a58e AT |
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 |