README.compile 10.5 KB
Newer Older
thomas.forbriger's avatar
thomas.forbriger committed
1
2
3
4
this is <README.compile>
============================================================================
How to compile the source code
------------------------------
5
$Id: README.compile,v 1.13 2010-07-16 09:10:53 tforb Exp $
thomas.forbriger's avatar
thomas.forbriger committed
6
7
8
9
============================================================================

Here you will find some notes to help you in the process of compiling software
provided by me (Thomas Forbriger). My programs usually make use of several
thomas.forbriger's avatar
thomas.forbriger committed
10
11
12
13
14
15
16
17
different software libraries.

With the beginning of 2006 I provide software packages (main code) separately
from the libraries, which makes life easier for me (but harder for you).
Please read the notes below to compensate for that.

From November 2007 on, I will port my programs to a 64-bit Linux system. Until
this is finished, you may find some of the packages in a transitional stage.
thomas.forbriger's avatar
thomas.forbriger committed
18
See also specific notes on Fortran code below (section Compilers).
thomas.forbriger's avatar
thomas.forbriger committed
19
20
21
22
23
24
25

Make
----
  In many cases you will need gmake (GNU make) to use the provided Makefiles.

Environment variables in Makefiles
----------------------------------
thomas.forbriger's avatar
thomas.forbriger committed
26
27
  The bevahiour of the Makefiles is controlled by environment variables. It is
  most suitable to set their values in $HOME/.profile or $HOME/.bashrc
thomas.forbriger's avatar
thomas.forbriger committed
28
  
thomas.forbriger's avatar
thomas.forbriger committed
29
30
31
32
33
34
35
36
37
38
39
40
  Here I give a description of these variables together with their typical
  values:

  export LOCBINDIR=$HOME/bin
    Compiled and linked binaries will be copied to this directory. If you
    include this directory in the setting of your PATH variable, you will have
    easy access to the binary from any working directory.

  export LOCLIBDIR=$HOME/lib
    Libraries will be copied to this directory. An Makefiles will pass this
    directory to the linker in order to link against these libraries.

thomas.forbriger's avatar
thomas.forbriger committed
41
  export LOCINCLUDEDIR=$HOME/include
thomas.forbriger's avatar
thomas.forbriger committed
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
    Links to header files will be installed in this directory. The Makefiles
    pass this directory to the preprocessor to look for header files.

  SERVERLIBDIR
    If libraries that are needed by this code (like PGPLOT) are installed in
    an uncommon system directory, you can use this variable to pass the
    location to the linker.

  SERVERINCLUDEDIR
    If header files that are needed by this code (like cpgplot.h) are installed
    in an uncommon system directory, you can use this variable to pass the
    location to the linker.

  LD_LIBRARY_PATH
    If you install external libraries (e.g. PGPLOT) in an uncommon place, you
    might have to set LD_LIBRARY_PATH to pass the location of the dynamic
    library (e.g. libpgplot.so) to the dynamic linker.

thomas.forbriger's avatar
thomas.forbriger committed
60
  export WWWBASEDIR=$HOME/doxydoc
thomas.forbriger's avatar
thomas.forbriger committed
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
    C++ libraries usually are distributed together with a set of documentation
    files that are automatically created by doxygen from the source code. The
    resulting HTML files or man-pages wil be installed in this place by the
    Makefile. The Makefiles create subdiretories to distinguish between
    different packages.

  export TF_BROWSER=firefox
    The Makefile support the display of doxygen documentation with your html
    browser. Use this variable to pass the name of the browser to the
    Makefile.

  export TF_LIBREGEXX=yes
    If this variable is set, the Makefiles will expect libregexx to be
    installed. Since libregexx is discontinued since several years and does
    not easily compile on 64-bit systems, my code will be ported to use the
    regular expression module in the boost library. This will be the default
    in the future. If you do not have the boost library installed, but
    libregexx, you should use this variable.
    This feature may disappear somewhere in the future.

thomas.forbriger's avatar
thomas.forbriger committed
81
82
83
84
85
  export TF_LINK_REGEXX=-lregexx
    Defines the linker option to link against regexx functionality. This can
    either be libregexx or libboost_regex. This variable and TF_LIBREGEXX must
    be set coherently.

thomas.forbriger's avatar
thomas.forbriger committed
86
87
88
89
90
91
92
93
94
95
  export TF_FALLBACK=yes
    During porting of the software to 64-bit systems, the default method of
    compiling Fortran code will be changed from f2c and gcc to g77. After this
    transition some Makefiles might no longer support f2c at all. At least the
    convetion for library file name will change. Until the porting procedure
    is finished for all packages, this variable can be used to use the old
    rules (f2c is default) as a fallback solution. Since filenames will be
    different in this solution you should use different settings for LOCBINDIR
    and LOCLIBDIR too, when using the fallback setting.

96
97
98
99
100
  export TF_LINK_FORTRAN=-lgfortran
    Define the linker option when doing interlanguage linking (i.e. link a C++
    main program against Fortran code from a library). Is you use g77, you
    will have to link against libg2c.a here.

thomas.forbriger's avatar
thomas.forbriger committed
101
102
103
104
105
106
107
108
109
110
111
112
113
  export TF_LINK_PGPLOT=-lpng -lX11 -L/usr/X11/lib64
    This variable is passed to the linker in cases where binaries have to be
    linked against PGPLOT. Use this variable to pass the location of your X11
    libraries as well as the names of additional libraries that might be
    needed for the PGPLOT drivers in your installation (like libpng.a in this
    example).

  export TF_f2c_PGPLOT=f2cpgplot
    Use this variable to pass the name of the PGPLOT library that was compiled
    with f2c and gcc (libf2cpgplot.a in this example).

  export TF_g77_PGPLOT=pgplot
    Use this variable to pass the name of the PGPLOT library that was compiled
thomas.forbriger's avatar
thomas.forbriger committed
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
    with gfortran (or g77, see below) (libpgplot.a or libpgplot.so in this
    example).

  The following variables will be used in Makefiles:
    CXX       name of C++ compiler command
    CC        name of C compiler command
    FC        name of Fortran compiler command
    CPP       name of C preprocessor command
  To the following variables local values may be appended in Makefiles:
    FLAGS     general flags (will be appended to other flag variables)
    CFLAGS    flags to C compiler
    FFLAGS    flags to Fortran compiler
    CPPFLAGS  flags to preprocessor
    CXXFLAGS  flags to C++ compiler
    LDFLAGS   flags to linker
thomas.forbriger's avatar
thomas.forbriger committed
129

thomas.forbriger's avatar
thomas.forbriger committed
130
131
132
133
134
135
136
137
138
139
140
Libraries
---------
  The library packages depend on each other. If you start compiling from
  scratch, you should install them in the following order:
    libaff:       base library, depends only on common system libraries
    libtime:      base library, depends only on common system libraries and
                  tfmacros.h (but includes tfmacros.h in the package)
    libtfxx:      base library, depends only on common system libraries and
                  STL (standard template library)
    libgsexx:     base library, depends only on common system libraries

141
    libsffxx:     depends on libgsexx, libaff, and libtime
thomas.forbriger's avatar
thomas.forbriger committed
142
143
    libdatreadxx: depends on libaff, libtfxx, libgsexx, libtime, libsffxx

thomas.forbriger's avatar
thomas.forbriger committed
144
145
146
tfmacros.h
----------
  The file tfmacros.h is available in package thofdevel########.tar.gz.
thomas.forbriger's avatar
thomas.forbriger committed
147
  It is used by several packages. Download and unpack this package and call
thomas.forbriger's avatar
thomas.forbriger committed
148
149
    /bin/cp -vpd tfmacros.h $LOCINCLUDEDIR

thomas.forbriger's avatar
thomas.forbriger committed
150
151
152
Comments in header files
------------------------
  Some Makefiles contain rules to strip comments from C++ and C header files.
thomas.forbriger's avatar
thomas.forbriger committed
153
  They use the program remcmmnt by Jari Laaksonen (see below). If this is not
thomas.forbriger's avatar
thomas.forbriger committed
154
155
156
157
158
  available to you, look for the variable REMCMMNT and set it to 
  REMCMMNT=cat

Compilers
---------
thomas.forbriger's avatar
thomas.forbriger committed
159
  With the transition to 64-bit systems, the default method to compile Fortran
thomas.forbriger's avatar
thomas.forbriger committed
160
  files will be gfortran (Fortran compiler in the GNU compiler collection).
thomas.forbriger's avatar
thomas.forbriger committed
161
162
  Most code will still compile with g77 if used consistently for all libraries
  too. Please use the FC environment variable to select your preferred Fortran
thomas.forbriger's avatar
thomas.forbriger committed
163
164
  cpmpiler. Notice that most code must be compiled with the -ff2c option set,
  to ensure proper interlanguage linking.
thomas.forbriger's avatar
thomas.forbriger committed
165

thomas.forbriger's avatar
thomas.forbriger committed
166
167
168
169
  Since I experience problems with return values from libf2c-functions on
  64-bit systems (see below), the support for f2c may be discontinued entirely
  in the future. Some libraries that provide features for inter-language
  linking (like libtime.a) may still require f2c to create a C-version of the
thomas.forbriger's avatar
thomas.forbriger committed
170
  Fortran source code. 
thomas.forbriger's avatar
thomas.forbriger committed
171
172
173
174
175
176
177
178

  Fortran code traditionally was compiled by f2c (netlib, see below) and gcc
  (GNU C compiler). For packages not yet ported to 64-bit, you may use the
  TF_FALLBACK environment variable to use the f2c rules in Makefiles (see
  above).

  Other Fortran compilers are not guaranteed to work properly with code
  provided here.
thomas.forbriger's avatar
thomas.forbriger committed
179
180
181
182

  C and C++ code usually is prepared to compile with the GNU C and C++
  compiler.

thomas.forbriger's avatar
thomas.forbriger committed
183
184
185
  I will not support the creation of 32-bit binaries on 64-bit platforms
  (which would be possible by using the -m32 option).

thomas.forbriger's avatar
thomas.forbriger committed
186
187
188
189
190
191
192
193
194
195
196
197
198
199
f2c
---
  The standard integer type for f2c compilation is "long int". The f2c-version
  I obtained together with openSuSE 10.2 provides a f2c.h that defines the
  Fortran integer type to be simple "int". That is reasonable since this keeps
  integer variables 4 byte long, which is necessary to keep binary i/o
  compatible for data files written on 32bit systems. However, the libf2c.a
  that is provided with this package apparently is compiled with integer being
  long int (8 byte on 64bit systems). Since f2c originally was designed to use
  long int integer types, it is very likely that this confusion may reappear
  elsewhere on 64bit systems, when using f2c. Since Fortran is supported by
  the GNU compiler collection I no longer see a reason to support f2c
  compilation.

thomas.forbriger's avatar
thomas.forbriger committed
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
Shell scripts
-------------
  Some make rules may still contain calls to shell scripts called newprog or
  newlib. A rule

    newprog $@

  can safely replaced by

    /bin/cp -vp $@ $(LOCBINDIR)

  Replace

    newlib $@

  by 

    /bin/cp -vp $@ $(LOCLIBDIR)

  Calls to newinclude, incdep or others are replaced as easily. Look for
thomas.forbriger's avatar
thomas.forbriger committed
220
221
  package thofdevel########.tar.gz, which contains those tools. You will find
  a copy of remcmmnt there too.
thomas.forbriger's avatar
thomas.forbriger committed
222

thomas.forbriger's avatar
thomas.forbriger committed
223
224
225
226
227
  The shell-script setsandbox is used to set the environment variable (see
  above) to independent values, when preparing a package. You will not need
  this shell-script, since you will not use the make rules for package
  creation.

thomas.forbriger's avatar
thomas.forbriger committed
228
229
230
231
232
233
234
235
236
Fortran plot programs
---------------------
  Plot programs usually link against PGPLOT (see below).

References
----------
  doxygen: www.doxygen.org
  PGPLOT: www.astro.caltech.edu/~tjp/pgplot/
  remcmmnt: Jari Laaksonen, http://cpp.snippets.org/ C++ collection
thomas.forbriger's avatar
thomas.forbriger committed
237
            A copy is placed in thofdevel########.tar.gz
thomas.forbriger's avatar
thomas.forbriger committed
238
239
240
241
242
243
244
245
246
  f2c: Netlib, http://www.netlib.org/f2c/

If you experience any problem, when compiling the code, please contact me:
--
| Dr. Thomas Forbriger      e-mail: Thomas.Forbriger@gpi.uni-karlsruhe.de  |
| Observatorium Schiltach (BFO), Heubach 206, D-77709 Wolfach, Germany,    |
| Tel.: ++49 (0)7836/2151, Fax.: ++49 (0)7836/7650                         |
| http://www-gpi.physik.uni-karlsruhe.de/pub/forbriger                     |
----- END OF README.compile -----