forked from Starlink/starlink
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME
397 lines (293 loc) · 15.1 KB
/
README
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
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
This directory contains the following directories:
libraries
Starlink Fortran/C libraries
applications
Starlink Fortran/C applications
etc
Starlink initialisation scripts
buildsupport
Starlink support applications required to build configure-based
Starlink applications.
thirdparty
Third party applications and libraries required to build
Starlink classic applications
pubs
Starlink publications
docs
General documentation not associated with a particular application
or library.
Building the Starlink source set from scratch
---------------------------------------------
To build the COMPLETE set of Starlink classic applications the following steps
are required. If you wish to do more elaborate things, then you should refer
to Starlink document SSN/78, which also contains some FAQs. Details of this
document are at the end of this README.
This procedure will not build the Starlink _Java_ applications. They are
built separately, using the procedure described in Java README
(currently these are available from the subversion repository at
https://starjava.jach.hawaii.edu/svn/trunk). You do not need to build any of
the Starlink classic applications to build the Java ones, unless you need to
rebuild the native parts of JNIAST, JNIHDS or SPLAT.
Preparation
-----------
- Specify where you want the installed files to end up (_PREFIX) and
where you want the build to find any previously installed Starlink
tree (_STARLINK). If there is no previously existing tree, then
set the two variables to the same value. Both variables default to
/star. You must have write access to the directory you name here.
Here and below we use /local-star as an example; in the examples
below substitute your own choice for this directory.
% setenv STARCONF_DEFAULT_STARLINK /local-star # csh
% setenv STARCONF_DEFAULT_PREFIX /local-star
or
% export STARCONF_DEFAULT_STARLINK=/local-star # sh
% export STARCONF_DEFAULT_PREFIX=/local-star
- Delete any previous Starlink environment variables.
% unsetenv INSTALL # csh
% unsetenv STARLINK
or
% unset INSTALL # sh
% unset STARLINK
and also make sure that an old-style Starlink system is not in your
PATH (since tools like messgen will get very confused).
You may also run into difficulties if you have previously sourced
the ${STARLINK}/etc/login and ${STARLINK}/etc/cshrc scripts that
existed from a previous classic mk-build Starlink install, as
even with $STARLINK removed from your PATH some applications may
still get confused at build time. If the login script in question
is a `new' one, from a previous autoconf install, you will
probably be fine (although you may need to remove installed
manifest files).
- Review any other environment variables that might affect the build.
For example, the variables F77, FC and CC will force the build
system to use the specified compilers. In particular, the default
IRAF installation sets the F77 variable to be a script which works
happily in most cases, but which will _not_ work with libtool, and
will cause the build to fail with opaque error messages about being
`unable to infer tagged configuration'. Unless you do wish to
force certain compilers to be used, it is probably better to unset
these variables before building the software. See './configure
--help' for a list of `some influential environment variables'.
This is good time to get the compilers that you're going to use
resolved, especially if you're not working on a GNU/Linux platform.
See the platform specific instructions later in this file.
At the time of writing (February 2009) it is known that the gfortran
compiler will work, but only from GCC4.3 onwards. If this is picked up by
default on your system you need to re-define FC and F77 to select another
compiler. For other versions of GCC4 you will need to use g95 (thanks to
Andy Vaught for his help with this), which is available from the g95 web
site: www.g95.org. For GCC3 based systems g77 should be used.
The build sequence
------------------
To build the complete source distribution, you go through the steps:
./bootstrap
make configure-deps
./configure -C
make world
Each of these steps is described in detail below.
- First bootstrap the system.
This downloads third-party software, builds and installs the buildsupport
system (the tools in the buildsupport directory, plus third-party
applications autoconf, automake and libtool), and then goes on to generate
the configure scripts which will be used in the next step. The autoconf,
automake and libtool applications have been patched specifically for
building this tree so any versions shipped with the OS, or installed by
you, will _not_ work. These applications will be installed into
$STARCONF_DEFAULT_PREFIX/buildsupport, so you should add
$STARCONF_DEFAULT_PREFIX/buildsupport/bin to the front of your PATH
at this point, BEFORE you run the ./bootstrap script. In order for the
`make' below to work, you also need to add the default bin
directory to your PATH, so you should do that now.
# csh-like
% setenv PATH $STARCONF_DEFAULT_PREFIX/bin:$STARCONF_DEFAULT_PREFIX/buildsupport/bin:$PATH
% ./bootstrap
or
# sh-like
% PATH=$STARCONF_DEFAULT_PREFIX/bin:$STARCONF_DEFAULT_PREFIX/buildsupport/bin:$PATH
% ./bootstrap
This step takes a long while. Note that, although an important part of the
./bootstrap script is running autoreconf in the top-level directory,
you should not run autoreconf yourself in this directory.
- Build the configure dependencies.
There are a _few_ components which have to be built and installed
before the main tree is configured. You will have been advised of
this at the end of the bootstrap process above, but in case you
missed that, the command is
% make configure-deps
- Finally configure and build everything.
Now configure and build the system. The dependencies within the
Makefile ensure that everthing is built in the correct order.
% ./configure -C # -C means caching results
% make world
If you need to give ./configure some help to find include files and
libraries (for example, you are on a Mac and have installed Fink in
/sw or OpenDarwin in /opt/local, or are on a Sun and have extra
software in /opt), then do so by setting (for example)
CFLAGS=-I/opt/local/include and LDFLAGS=-L/opt/local/lib either in
the environment or, better, as arguments to the ./configure script.
Don't do this unless you discover you have to.
Each of these steps can also take some non-trivial time.
Additional hints
----------------
- Disabling shared libraries
If you wish to disable the building of shared libraries you should
use the --disable-shared configure option when you give the
./configure command above.
% ./configure -C --disable-shared
- Disabling the documentation
By default, the system will be configured so that all documentation
is built at the same time as the software. For this to work, you
must have LaTeX installed on your machine. Building the documentation
is rather slow, and you can speed up the build somewhat by omitting it.
You do that as follows:
% ./configure -C --without-stardocs
- Building a single library or application
If you wish to build only as far as a given component, then specify
it by giving the name of the associated `manifest' file.
% make /local-star/manifests/ast
This will build, and install under STARCONF_DEFAULT_PREFIX, this
component and _everything it depends on to be built_.
Developing individual components
--------------------------------
Note that this sequence of
./bootstrap; make configure-deps; ./configure -C; make world
is indeed a `make world' command -- it builds everything in the repository
that has been brought into the configure-based system, and will fail if some
components have not been checked out. If you wish to build or develop a
specific component, the instructions are slightly different.
- Specify the _PREFIX and _STARLINK variables as before, though this
time it might be appropriate to give them different values, if you
want to build against one installation tree (_STARLINK), but
install into another (_PREFIX). As above, unset the INSTALL and
STARLINK variables, and make sure there is no old-style Starlink
system in your PATH.
- If you have already built the buildsupport tools (autoconf,
automake, libtool and starconf), then make sure these are in your
PATH. If they are not built, or if you are not sure they are
up-to-date, you can build just these by going to the top-level of
your checkout and giving the command
% ./bootstrap --buildsupport
- Now you can go into a specific directory and build the library or
application as normal (a bootstrap is required in the directory if
you are building from a subversion checkout)
% ./bootstrap
% ./configure -C
% make
% make install
- After updating a component from the repository, it is possible that some
generated files will be out of date (if configure.ac or Makefile.am
had been updated). Any required updating is generally handled
automatically by makefile rules, but if you wish to guarantee that
everything is up to date, then you can give the command
`autoreconf'. This does no harm in any case, since it does nothing
if it is not required. As noted above, the exception to this is
that you should not run autoreconf in the top-level directory.
Updating the source set
-----------------------
The `make world' command will not _re_build the tree after you do an update
from the source repository, possibly unexpectedly. For a detailed explanation
of why this is so, see the `General FAQs' in SSN/78, described below.
You should also run the ./update-modules script after performing an update
of the source set from the main repository. This will make sure that any
thirdparty code is also updated.
Platform specific build notes
-----------------------------
- GNU/Linux
Currently (February 2009) the source set is known to build on many different
flavours of GNU/Linux and is actively developed using these. The only expected
issue is that of Fortran compiler support (C, C++ and Fortran compilers are
required to build the complete collection).
After the release of GCC 4 the Fortran compiler "g77" has been replaced with a
completely new "gfortran" (that now implements Fortran 90, 95 and some 2003
features), which has not been compatible with Starlink Fortran until the
release of version 4.3. Happily this turned out to be not a major problem
(thanks to Andy Vaught) as the other free Fortran compiler "g95", is
compatible. So to build the collection with a GCC 4+ compiler you'll either
need a copy of "g95" which is available from "www.g95.org", or more a very
recent version of gfortran (this can be checked by running gfortran -v).
To make sure you use the "g95" or "gfortran" compilers as required it is best
to define the environment variables "FC" and "F77":
% setenv FC g95 # csh
% setenv F77 g95
or
% export FC=g95 # sh
% export F77=g95
or
% setenv FC gfortran # csh
% setenv F77 gfortran
or
% export FC=gfortran # sh
% export F77=gfortran
before running "configure".
- Ubuntu (>= 11.04 "Natty Narwhal) / Debian
As of version 11.04 of Ubuntu the default handling of shared library
linking has changed. In the past indirect linking was enabled, such
that a program could link library "A", which in turn uses library
"B", and without explicitly linking the latter, routines from "B"
would be available (a situation that occurs in Starlink). Now that
this capability has been disabled, you will likely see strange
linker errors if you follow verbatim the build instructions as
described earlier in this document.
To remedy this situation you need to re-activate indirect linking
with LDFLAGS when configuring the build:
% ./configure -C --LDFLAGS=-Wl,--no-as-needed
According to the following web page, it is also likely that this
problem will occur with Debian (at some point), although it has not
been tested:
https://wiki.ubuntu.com/NattyNarwhal/ToolchainTransition
- OS X
The build situation under OS X follows much like that of GNU/Linux,
but you'll need to install your own Fortran compiler. In 10.3
the "g77" compiler from "Fink" or "MacPorts" has been used successfully,
in 10.4 you'll need a copy of "g95". For 10.5 or later you can use
g95, or gfortran. The latter is available from hpc.sourceforge.net
as well as MacPorts.
Note you'll also need a development installation of the Apple X11
environment, and a functioning TeX and Ghostscript if you want to build the
documents.
- Solaris
The collection is known to build under Solaris 8 (sparc) and 10 (intel),
using the SUN compilers (Workshop 6 and studio 11 respectively). To make
sure the correct compilers are picked up, you should define:
% setenv FC f77 # csh
% setenv F77 f77
% setenv CC cc
% setenv CXX CC
or
% export FC=f77 # sh
% export F77=f77
% export CC=cc
% export CXX=CC
Further information
-------------------
The Starlink document SUN/248 gives further advice about building Starlink
classic applications, including some old, out-of-date, platform-specific
notes. A version is currently (May 2006) available at
<http://www.astro.gla.ac.uk/users/norman/star/sun248/>.
The source is in the repository at docs/sun/248.
You should consult the project web pages at <http://www.starlink.ac.uk>,
<http://starlink.jach.hawaii.edu> and consider subscribing to the Starlink
development and user mailing lists: see
<http://www.jiscmail.ac.uk/archives/starlink.html> and
<http://www.jiscmail.ac.uk/archives/stardev.html>.
Starlink document SSN/78 gives much more detailed information on the
process of building Starlink classic applications, but this document
is primarily concerned with documenting the build system itself, and
describing how to add new components to the build-system repository.
The source for this document is in the repository at docs/ssn/078, and
a built version should be available on the Starlink web pages. A
version is also currently (May 2006) available at
<http://www.astro.gla.ac.uk/users/norman/star/ssn78/>.
This document contains some FAQs: a few of these will likely be of
interest to thise building the system from a checkout, though most
address quite specific details of how to configure software to work
within the Starlink source tree.
git repository
--------------
In February 2009 the Starlink source code was moved to a git repository
at the JAC Hawaii. This is described by a wiki at:
http://starlink.jach.hawaii.edu/
The build procedures described above are still correct, but much of the
associated documentation, SSN/78 etc. are becoming rapidly out-of-date.
Consult the wiki for download instructions and how to access things like
specific releases.