-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathREADME.html
256 lines (256 loc) · 14.6 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
<HTML> <!-- hfm V2.3/0b218 generated this HTML document -->
<HEAD> <font size=2 >
</head> <body>
<font size=3 >
<p>
<a name="NngSrcRls"></a>
<p><h1>NINGAUI SOURCE RELEASE </h1>
<font size=3 >
This directory contains the official release of Ningaui source, documentation, and possibly other things. If you are interested in a quick start, see the last section of this document.
<a name="Hrdwrndprt"></a>
<p><h2>Hardware and Operating System </h2>
<font size=3 >
Ningaui clusters have been created using a mix of various hardware and operating system flavours. The hardware platforms that have been successfully used include: x86 (32 and 64 bit) style processors, Power PC, Sun SPARC, and SGI.
<p>Ningaui software has been built and used successfully under the following operating systems:
<p>
<ul><div>
<ul>
<li>FreeBSD 4.x, 5.x and 6.x
<li>Linux 2.x (RedHat and SuSe, YellowDog)
<li>Darwin 7.x and 8.x (Mac OSX)
<li>Irix 6.x (SGI)
<li>SunOS 5.x
</ul>
</ul></div>
<a name="SftwrRqrmn"></a>
<p><h2>Software Requirements </h2>
<font size=3 >
The following software tools are assumed to be installed on a Ningaui node:
<p>
<ul><div>
<ul>
<li>Gnu awk (gawk) v3.1.1
<li>Ruby 1.8 or later
<li>AT&T Korn shell (ksh93) Version r or later.
<li>AT&T AST pax (2005-12-14 or later)
</ul>
</ul></div>
<p>During node startup, Ningaui software locates each of these tools and sets symbolic links in $NG_ROOT/common, and $NG_ROOT/common is included in the PATH. Warnings are issued if they are not found where expected. If one of these software components
is not installed, Ningaui software behaviour might not be as is desired, though on the surface everything might appear to be operating without problems.
<a name="RlsCntnts"></a>
<p><h2>Release Contents </h2>
<font size=3 >
The following is a brief description of the directories and files contained here:
<p>
<table width=90% border=0 > <font size=2 >
</font></td><tr><td valign=top width=12%><font size=3 ><b>
contrib
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Contains source for libraries and/or tools that were written independently of the ningaui project. The ningaui project depends on these tools.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
doc
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Ningaui documentation is contained within subdirectories of this directory. The <tt>manuals</tt> subdirectory contains the user's guide, programmer's guide and an installation and administration manual. Most documents are supplied in HTML, Postscript,
PDF, and plain ASCII formats. (Note that the plain ASCII text versions do not completely support some of the table formatting used in the documentation. Best to view the documents using one of the other formats; ASCII is supplied for use in a pinch.)
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
mkfile
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Mkfile that can be used to build the source.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
ng_build.ksh
</b></font></td><td valign=top><font size=3 >
<font size=3 >
A Kshell script that is used to prepare the build environment, and to optionally take the necessary steps to compile all of the contrib and potoroo software.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
panoptic.mk
</b></font></td><td valign=top><font size=3 >
<font size=3 >
A global mkfile that is included by all mkfiles in the ningaui source tree.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
panoptic.ksh
</b></font></td><td valign=top><font size=3 >
<font size=3 >
A Kshell script that is invoked by panoptic.mk to help establish the build environment.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
potoroo
</b></font></td><td valign=top><font size=3 >
<font size=3 >
The base set of software for project Ningaui.
</table><p>
<font size=3 >
<a name="BldGnrtdDr"></a>
<p><h2>Build Generated Directories/Files </h2>
<font size=3 >
During the build process, several directories and files are created in this upper directory. This is a list of the ones that might be of interest:
<table width=90% border=0 > <font size=2 >
</font></td><tr><td valign=top width=12%><font size=3 ><b>
stlib
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Directory that will contain Ningaui and contrib libraries after the source has been 'precompiled.'
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
include
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Header files for libraries.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
.bin
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Tools that are used during the build processes.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
bld_root
</b></font></td><td valign=top><font size=3 >
<font size=3 >
A temporary NG_ROOT directory created if the <tt>-r</tt> option is not supplied to <tt>ng_build.ksh</tt>
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
manuals
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Target directory for HTML and text man pages that are generated during the build process. The man pages are contained in the subdirectories <tt>html</tt> and <tt>text.</tt>
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
build_log
</b></font></td><td valign=top><font size=3 >
<font size=3 >
This file is created by the ng_build.ksh script if the -a (build everything) option is given.
</table><p>
<font size=3 >
<a name="MkngNng"></a>
<p><h2>Making Ningaui </h2>
<font size=3 >
Building Ningaui consists of compiling the source into binaries for the target machine, and then bundling sciripts, binaries, and other needed files into "packages" which can be distributed and installed on machines with like hardware and
operating system. Before executing the build, you must ensure that the korn shell (ksh) is available in one of several common locations, or that the path to Kshell is provided to the script using the <tt>-s</tt> option. If the <tt>-s</tt> option is
not used, these locations are searched for an executable copy of Kshell:
<p>
<ul>
<li>/usr/common/ast/bin
<li>/usr/local/bin
<li>/usr/bin
<li>/bin
</ul>
<p>The public domain version of Kshsll (pd-ksh) is often installed by default on various UNIX systems and that version is <b>NOT</b> compatable with Ningaui software.
<p>To build Ningaui, and create the potoroo and contrib distribution packates, execute the command:
<p>ng_build.ksh -v -a [-p]
<p>The build consists of several steps
<p>
<table width=90% border=0 > <font size=2 >
</font></td><tr><td valign=top width=12%><font size=3 ><b>
Build mk
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Ningaui needs mk; this step builds it.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
Precompile
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Setup and compiles libraries; populates ./stlib.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
mk all
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Builds Ningaui binaries.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
Install
</b></font></td><td valign=top><font size=3 >
<font size=3 >
Installs Ningaui into a directory within the current build directory (this is not a system install).
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
Generate Man Pages
</b></font></td><td valign=top><font size=3 >
<font size=3 >
The ningaui manual pages are created and placed into ./manuals/html and ./manuals/text. Ningaui scripts and binaries carry their manual page 'on board' and use their on board copy when the '--man' option is given on the command line. These directories
provide a reference set of manual pages that can be accessed via HTTPd or editor without the need to have ningaui software installed.
<p>
</font></td><tr><td valign=top width=12%><font size=3 ><b>
Generate Packages
</b></font></td><td valign=top><font size=3 >
<font size=3 >
This step creates the 'binary packages' for the potoroo and contrib software, provided that the -p option was given on the command line. These packages are simple tar files that can be uncompressed and extracted on any target cluster node of the same
type and O/S flavour used to compile the package.
</table><p>
<font size=3 >
<p>If you specify the all option (-a), then you may specify the package option (-p). This option will create the package tar files that can easily be used to install Ningaui on other hosts.
<p>If you wish to build the ningaui software manually, then execute <tt>ng_build.ksh</tt> without the all option to setup the various directories. Once the directory tree has been properly established, a set of instructions will be written to the
standard error device. These instructions list the steps necessary to build the ningaui software.
<a name="MkvsMk"></a>
<p><h3>Mk vs. Make </h3>
<font size=3 >
The ningaui software is built using the <tt>mk</tt> tool from <i>Plan9</i>. <tt>Mk</tt> is a make-like tool used to maintain dependances between files and to properly build and/or install files when they are 'out of date.' More information about
<tt>mk</tt> can be found via this URL:
<br>
<a href="http://cm.bell-labs.com/sys/doc/mk.html">http://cm.bell-labs.com/sys/doc/mk.html </a>
<p>Because ningaui uses <tt>mk</tt> to build things, mk must first be compiled and installed. This is the first task undertaken by <tt>ng_build.ksh</tt> when run with the build all option. The <tt>mk</tt> binary is placed into the <tt>./.bin</tt>
directory where it can be referenced by the rest of the build process.
<p>When using <tt>ng_build.ksh</tt> to compile everything, there is no need to worry about making the <tt>mk</tt> programme. However, if manually compiling everything, it will be necessary to switch to the <tt>contrib</tt> directory, and then to
execute the <tt>ng_build.ksh</tt> script which builds mk.
<p>In general the tools in the <tt>contrib</tt> directory are used 'as is;' we have included them in accordance with any 'right to use and distribute license' that they contain, and have made little or no changes to their source. This includes not
converting their build management (make or gmake) files to <tt>mk</tt> In most cases we have created a <tt>mkfile</tt> which acts as a wrapper and invokes <tt>make</tt> or <tt>gmake</tt> in order to build the contributed tool(s). It is for this reason
that ningaui does require that <tt>gmake</tt> be installed on the build host.
<p>
<a name="thrBldSppr"></a>
<p><h3>Other Build Support Tools </h3>
<font size=3 >
In addition to <tt>mk</tt>, the ningaui build process relies on the <tt>tfm</tt> and <tt>hfm</tt> tools in the <tt>Xfm</tt> text formatting suite; a part of the <tt>contrib</tt> directory. After <tt>mk</tt> is compiled, the <tt>Xfm</tt> suite of
programmes are compiled and installed in <tt>./bin.</tt>
<a name="hRmndrfCnt"></a>
<p><h3>The Remainder of Contrib </h3>
<font size=3 >
The remainder of the tools contained in the <tt>contrib</tt> directory are tools and libraries that are needed by ningaui programmes and scripts. The libraries are compiled and placed into ./stdlib
<a name="MnlPgs"></a>
<p><h2>Manual Pages </h2>
<font size=3 >
Ningaui software implements manual pages as 'self contained documentation.' Supplying the <tt>--man</tt> option on the command line of any Ningaui tool will result in the manual page being formatted and displayed on the standard output device.
The output text is piped through the pager application listed by <tt>PAGER</tt> in the environment, or through <tt>more</tt> if <tt>PAGER</tt> is not defined.
<p>The main theory behind SCD is that the manpage is maintained as a part of the source code (easily found at the bottom of each script or programme), ensuring that the manual page displayed matches the tool being executed. Another benefit of SCD is
that when changes are made to the source, it is easier to update the documentation because a second file does not need to be edited.
<p>The markup language that the manual pages are written in (XFM) can also produce HTML output allowing a set of Ningaui manual pages to be made available from any httpd environment. To make the HTML manual pages, the command <tt>`mk manpages`</tt>
needs to be executed in the top level directory. The HTML files generated are placed into the <tt>manuals</tt> directory and then can be moved to the desired httpd directory tree.
<a name="nstlltn"></a>
<p><h1>INSTALLATION </h1>
<font size=3 >
Ningaui must be installed into a directory referred to a the 'ningaui root,' and referenced by the environment variable <tt>NG_ROOT.</tt> Generally, the ningaui root is <tt>/ningaui,</tt> though it can be anything. Once the ningaui root is
created, the packages generated during the build process can be installed with the command:
<p>
<pre>
ksh ng_build.ksh -v -i $NG_ROOT
</pre>
<p>This command will take the packages in the current directory and install them into the ningaui root directory.
<p>The package files are simple tar files and can be extracted into the desired location manually, or the contents of the bld_root directory can be copied to a desired location if using the automated process is not desired.
<p>Once the software is installed, the node must be configured before it can join the cluster. Please refer to the Ningaui Installation and Administration documentation (see doc/manuals) for details on how to properly set up a node and/or cluster for
ningaui.
<a name="QckStrt"></a>
<p><h1>QUICK START </h1>
<font size=3 >
Don't like reading the instructions? To build the ningaui software in this directory, and to install it in a subdirectory beneath this directory (bld_root), the following command can be executed:
<p>
<pre>
ng_build.ksh -v -a [-p]
</pre>
<p>Some verbose messages will appear on the standard error device, and the compile output will be written to <tt>build_log</tt> in the current directory. If the build is successful, then <tt>./bld_root/bin</tt> will have the binaries,
<tt>./bld_root/lib</tt> will have some needed support files. Set the environment variable NG_ROOT to reference <tt>$PWD/bld_root</tt> and you are all set to use the ningaui tools (you might want to read the manual about how to start them on the node!)
<p>Install the packages created by the previous command (assuming -p was used) with the following command:
<p>
<pre>
ksh ng_build.ksh -v -i $NG_ROOT
</pre>
<p>The software must be setup (configured) before the node can join the cluster. The details on how to set up a node, or the cluster, are in the Ningaui Installation and Administration documentation.
<hr>
</font></body></HTML>