Mercurial > ~dholland > hg > ag > index.cgi

comparison doc/install/install.txt @ 0:13d2b8934445

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import AnaGram (near-)release tree into Mercurial.
author David A. Holland
date Sat, 22 Dec 2007 17:52:45 -0500
parents
children 4b08ee1ecb99
comparison
equal deleted inserted replaced
-1:000000000000 0:13d2b8934445
1 Installing AnaGram 2.40 from source
2 -----------------------------------
3
4 1. Requirements
5
6 You must compile on Unix. (Windows using Cygwin is not presently
7 supported, but suitable patches will be accepted. Windows without
8 Cygwin or equivalent is too crippled to be useful.) Any reasonably
9 modern Unix should work, even Solaris, although this has probably not
10 been tested. (Linux, NetBSD, and perhaps MacOS X are tested.)
11
12 The makefiles have been arranged such that even the antiquated
13 dialects of System V make shipped by Sun and other old-line Unix
14 vendors should work; if you find that you need GNU make please file a
15 bug report.
16
17 There are essentially two supported builds: the Unix command-line-only
18 build and the Windows GUI build.
19
20 The Unix build currently requires gcc 3.x or 4.x. Reasonable patches
21 for other Unix compilers (e.g. the Intel compiler on Linux, or Sun's
22 payware compiler) will probably be accepted. If you have gcc set up as
23 a cross-compiler, you can cross-compile AnaGram. See below.
24
25 The Windows build requires IBM Visual Age for C++ version 3.5, because
26 the GUI uses that compiler's semi-proprietary GUI class library. You
27 also need a recent version of Wine.
28
29 Wine must be configured such that I:\\IBMCPPW\\BIN\\ICC.EXE is the
30 main compiler executable. (To arrange this, create a suitable symbolic
31 link named "i:" in ~/.wine/dosdevices.) Note that while it would not
32 be difficult to make this more flexible, migrating away from this
33 compiler is a better use of time.
34
35 The source tree must also be accessible to Wine somehow; it doesn't
36 matter what the specific drive or path mapping is.
37
38 At one time it was necessary to use patchlevel 354 (neither newer nor
39 older) of ILINK.EXE, which you can get from IBM support. This version
40 is 188928 bytes long and has md5sum f48f0aace7c6f247bae015b43f16969a.
41 Wine has improved a good deal since then, however, and this may no
42 longer be necessary.
43
44 Because of problems with Wine on NetBSD, you can only compile the
45 Windows build on NetBSD with some combinations of versions of NetBSD
46 and of Wine. Linux works, however.
47
48 Note that the source, though not the build system, has some support
49 for a number of other Windows compilers (including Borland, Watcom,
50 and Microsoft) and you may be able to get these to work to build the
51 command-line-only version. Building a Windows command-line only
52 version using a Cygwin gcc may also be possible. These builds,
53 however, are unsupported and you will have to fiddle with the
54 configure script and/or the makefiles. (Appropriate patches will
55 probably be accepted though.)
56
57 Building the manual requires LaTeX. It doesn't require anything that
58 doesn't come with teTeX, so no unusual steps should be necessary.
59
60
61 2. Configuring
62
63 AnaGram comes with a "configure" script that sets up the build
64 environment. This is *not* a GNU autoconf script, although it looks
65 superficially like one.
66
67 It accepts the following options:
68
69 --destdir=DIR
70
71 Set the "destination directory" to DIR. This names a chroot
72 area or other subtree within which the installation prefix
73 will be found. The idea is that the destination directory will
74 end up being the root directory at the time AnaGram is run.
75 This is potentially useful for cross-compiling and for
76 building binary packages.
77
78 Note: this applies only to Unix builds.
79
80 --prefix=DIR
81
82 Set the installation prefix to DIR. Defaults to /usr/local.
83 The AnaGram executables, documentation, and examples will be
84 installed in suitable places under this directory by default.
85
86 AnaGram does not (at present) compile in the installation
87 prefix.
88
89 Note: this applies only to Unix builds.
90
91 --bindir=DIR
92 --libdir=DIR
93 --mandir=DIR
94 --docdir=DIR
95 --examplesdir=DIR
96
97 Set the exact places where things will be installed. If these
98 are not provided, suitable defaults under the installation
99 prefix are chosen. Note that depending on the build and other
100 circumstances some of these directories may not actually be
101 used.
102
103 Note: these options apply only to Unix builds.
104
105 --with-compiler=COMPILER
106
107 Specify which compiler to use. This controls the selection of
108 compiler command-line options, C++ dialect, and other such
109 issues. It also controls how the compiler is invoked.
110
111 COMPILER may be "gcc" for gcc or "vacpp" for the IBM Visual
112 Age compiler.
113
114 The default compiler is gcc for Unix builds and vacpp for
115 Windows builds.
116
117 --with-ptests=DIR
118
119 If you have a copy of the private test suite, use this
120 argument to tell the build system where to find it. The
121 private test suite contains tests that for one reason or
122 another cannot be released to the public.
123
124 --enable-gui=GUI
125 --disable-gui
126
127 Select the graphical user interface to use. The only GUI
128 currently supported by AnaGram is "vaclgui", the GUI using the
129 Visual Age class library. Enabling "dummygui" is equivalent to
130 selecting --disable-gui.
131
132 "vaclgui" is the default for Windows builds. "dummygui" is the
133 default for Unix builds.
134
135 --enable-maintainer-mode
136
137 Turn this on if you are intending to work on the AnaGram
138 source code. It enables compiler flags that developers should
139 use. It also enables certain crosschecks, and compilation and
140 testing of the examples. Note that to use this you must
141 populate your tree with a known clean copy of the agcl
142 executable. See doc/devel/make.txt for more information.
143
144 --enable-debug
145
146 Compile with debug information. The default is to compile with
147 optimization.
148
149 --enable-prof
150
151 Compile with profiling support. This will not work at present
152 with the IBM compiler because I don't know what compiler
153 switches to use. (Patches/information welcome.)
154
155 In addition to options, the configure script accepts an argument
156 naming the platform to compile for. This can be one of the following:
157
158 native
159
160 Build for Unix, and don't cross-compile.
161
162 windows
163
164 Cross-compile for Windows.
165
166 mips-linux
167
168 Cross-compile for some other Unix type. The string provided
169 should be the GNU machine type name for a cross-compiling gcc
170 you have previously installed. See below.
171
172 The default is "native".
173
174 It is recommended that you not compile directly in the source tree.
175 Make a directory to build in, and run the "configure" script from that
176 directory, giving the path to the source, such as like this:
177
178 mkdir build-windows
179 cd build-windows
180 ../configure windows
181
182 The build directory can be put anywhere, and you can use multiple
183 build directories with the same source directory. If you intend to
184 work on the AnaGram source code, you should generally set up one build
185 directory each for Unix and Windows, and of course use the
186 --enable-maintainer-mode option.
187
188
189 3. Compiling
190
191 In the same directory you ran the configure script, do this:
192
193 make rules
194 make
195
196 If you do not do "make rules" first the build will bomb out very
197 quickly.
198
199 (Why is "make rules" not automatically invoked by the configure
200 script? Because it creates a lot of scroll, particularly with GNU
201 make, and would obscure possibly important messages issued by the
202 configure script.)
203
204 Do not do parallel builds (make -j3 or similar) -- it will not work.
205 Note that GNU make is incapable of handling this correctly in any
206 event, so support is not likely to be forthcoming in the future.
207 Flames to /dev/null.
208
209
210 4. Testing
211
212 To run the test suite, do this:
213
214 make test
215
216 (Note that "make tests" will do nothing, because there's a directory
217 named "tests".)
218
219 If everything is working correctly, there should be no diffs printed.
220
221 As of this writing, if you run the test suite for the Windows build,
222 you will get various test diffs because of messages issued by Wine, as
223 well as some changes in diagnostic messages caused by the different
224 end-of-line markers. These diffs appear to be benign, although it
225 would be better if they didn't happen at all.
226
227 Also note that you need to have an X display to run the test suite
228 under Wine, even though the test suite only tests the command-line
229 AnaGram executable. It is not immediately clear why this is.
230
231
232 5. Installing
233
234 To install, do this:
235
236 make install
237
238 For the Unix build this will install in the places selected at
239 configure time.
240
241 For the Windows build it will create a directory called "install"
242 containing a binary release comparable to the historic binary releases
243 of AnaGram. You can copy this to a suitable place on your Windows
244 machine however you see fit.
245
246
247 6. Running AnaGram
248
249 For the command-line version, run "agcl". For the GUI version, run
250 "ag". For further information, please consult the main AnaGram manual,
251 or the additional HTML documentation found in doc/misc; the latter
252 includes a Getting Started guide.
253
254 Note that the Visual Age for Windows GUI version does not work all
255 that well in Wine; it seems to have various problems updating the
256 screen and seems unable to select fonts properly. (This makes the
257 Grammar Trace and related functionality very difficult to use.) It
258 does not run at all in Wine on NetBSD, either. Fixes will probably be
259 accepted - but keep in mind that the Visual Age class library is
260 orphaned and time would be better spent migrating to a new GUI using
261 some other GUI toolkit.
262