/
README
199 lines (138 loc) · 7.28 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
README CONTENTS
This file contains general information for a variety of users:
INSTALLATION BASICS general installation information
GRAPE SYSTEMS additional information for GRAPE sites
PROGRAMMERS information for Starlab programmers
DEVELOPERS information for Starlab developers
COPYRIGHTS ownership, attribution, and contribution
INSTALLATION BASICS
- We assume here that the variable STARLAB_PATH points to the top-
level Starlab source directory (i.e. the one containing this file).
GRAPE users should read the GRAPE section below before starting
the configure/build process.
- Installation proceeds in GNU standard fashion:
./configure --prefix=STARLAB_INSTALL_PATH --other-options
make
make install
See the INSTALL file in this directory for more information. The
current default STARLAB_INSTALL_PATH is
$STARLAB_PATH/usr
and in normal circumstances no other options need be specified.
- Both STARLAB_PATH and STARLAB_INSTALL_PATH will be created as
environment variables by the starlab_start scripts generated as
part of the installation process. (They are convenient, although
neither is actually needed for routine operation of the software.)
- If you downloaded Starlab in the form of a distribution tarball
(named starlab-version.tar.gz), the configure script should already
exist in $STARLAB_PATH, and you can proceed directly to the above
standard installation commands.
- However, if you obtained Starlab from the CVS archive, then the
source tree will not include the configure script. You will have
to create configure (and other installation files, such as
"Makefile.in") using the command
autoreconf -i -f
Starlab now makes extensive use of the GNU "autotools," aucoconf,
autoreconf, automake, and libtool. Unless you are sure that your
system has versions of these tools newer than those used to build
the package, you probably first will want to install the autotools
found in $STARLAB_PATH/src/packages. You can do this by hand
(unpack the tarballs and follow the installation instructions), or
by running the script
install-autotools
found in that directory. You will also have to modify your search
path to ensure that the directory containing the newly installed
autotools *precedes* any system directory before proceeding with
the Starlab installation.
Once you have run autoreconf, you can again proceed to the standard
installation commands given above. Note that if you are installing
from a tarball, you should only need autotools if you modify any of
the "Makefile.am" templates in the source directories.
- If you prefer to install everything automatically, in all cases you
can simply run the script
install-starlab
in this directory. This script performs the various actions just
described (including autotool installation in all cases), and in
addition it provides timing information and attempts to clean up the
"make" output. It also contains workarounds and corrections for
some known deficiencies of the configure/make proocess.
- Once the package is successfully installed, to use the Starlab tools,
make sure that the directory
$STARLAB_INSTALL_PATH/bin
is in your search path, preceding any system files. You may also
find it useful to include the Starlab administrative directory
$STARLAB_PATH/sbin
Sourcing the script $STARLAB_PATH/starlab_start.csh (or its .sh
equivalent, for bash users) will automatically set up the environment
variables
STARLAB_PATH
STARLAB_INSTALL_PATH
STARLAB (= STARLAB_PATH, included for compatibility)
STARLAB_VERSION
and will also appropriately modify the search path.
GRAPE SYSTEMS
- It is very difficult for the configure script to infer automatically
the existence of a GRAPE or to determine the appropriate GRAPE
libraries and other settings to use. If you have a GRAPE, you will
have to place that information in the file
$STARLAB_PATH/local/grape.sh
This file is a simple shell script that sets a few variables used
to build the Makefiles. So that it cannot be overwritten by a new
release after you have created it, the script itself is not distributed
with the Starlab package. However, a template is distributed in
$STARLAB_PATH/local/grape.sh.template
and a collection of examples from various GRAPE sites is contained
in
$STARLAB_PATH/local/grape.sh.examples
You will have to rerun configure after creating or changing this
script, so you will probably want to make these changes BEFORE building
the system! If you don't have a GRAPE, do nothing, and Starlab will
by default build a system without GRAPE acceleration.
- If you change any of the scripts in $STARLAB_PATH/local (e.g. to
change the name or location of the GRAPE library ), you will have to
rerun configure in order for the changes to find their way into the
relevant Makefiles. Simply updating a library does not require
reconfiguration, but note that (for now) make will not automatically
detect the change, so you will have to explicitly rebuild all GRAPE-
dependent programs (kira, sys_stats, scale, etc.). It is probably
simplest to use sremake to accomplish this (see below).
PROGRAMMERS
- For programmers, the Starlab header files are installed in
$STARLAB_INSTALL_PATH/include/starlab
and the libraries are in
$STARLAB_INSTALL_PATH/lib/starlab
To use them, it should be necessary only to include lines like the
following in your Makefile (the "-l" libraries may differ -- these are
for a dyn target):
CPPFLAGS = -I$(STARLAB_INSTALL_PATH)/include/starlab -DHAVE_CONFIG_H
LDLIBS = -L$(STARLAB_INSTALL_PATH)/lib/starlab -ldyn -lnode -lstd -lm
DEVELOPERS
- The new configuration procedure produces a lot of output, which may
become annoying if you find yourself repeatedly rebuilding programs as
you debug them. To reduce the volume of diagnostic information coming
from the make process, use "make -s" or the 'smake' script found in
$STARLAB_PATH/sbin. Smake will build the specified target, starting
the process at the top level (i.e. at $STARLAB_PATH), using "make -s"
option to suppress extraneous output.
- The current configuration currently creates duplicate copies of objects
and executables -- local versions are used to build the package, and
these are then copied into the install directory by 'make install.'
This can be confusing, as it is very possible to rebuild a program
without installing it, thus creating two versions and causing confusion.
We recommend always rebuilding libraries from the top level with
smake libs
which will guarantee that all local libraries are updated, and
rebuilding programs with
sremake program
which will rebuild all outstanding libraries, then delete, rebuild,
and properly install the executable.
- If the autotools are properly installed, developers should find that
any changes made to the automake "Makefile.am" files will cause the
relevant Makefiles to be automagically regenerated the next time make
is involked.
- If you modify the configure.ac script in $STARLAB_PATH, you *MUST*
run autoreconf before running configure again.
COPYRIGHTS
- see the COPYING file in this directory for information on the GPL.
- for use and attribution policies, see the README file in
"doc/README", or
http://www.sns.ias.edu/~starlab/policies