|Ask a Question||Search PSRCHIVE:|
PSRCHIVE developer's guide
IntroductionThe PSRCHIVE software makes use of the GNU autotools to compile the source code and install the header files, scripts, libraries and binary executables. An introduction to GNU autoconf, automake, and libtool is available as The Goat Book. Developers with an interest in writing robust and portable code may also take interest in the GNU coding standards. If you have been developing with the old setup, it would be good to follow the notes on switching to the GNU autotools.
Check-out, bootstrap, configure, and compile
Check-outDevelopers may check out the software from the SourceForge.net Git repo with
$ git clone ssh://USERNAME@git.code.sf.net/p/psrchive/code psrchivewhere USERNAME is a valid PSRCHIVE sourceforge user account login id. Upon successful checkout, a single directory, psrchive, will be created in the current working directory. If this is the first time you have checked out the software, the psrchive directory will contain the following files and directories:
AUTHORS config/ Doxyfile psrchive_cflags.in* Util/ Base/ configure.in Makefile.am psrchive_ldflags.in* bootstrap* COPYING More/ README ChangeLog NEWS upload.csh*The directories shown in white are the main directories of the PSRCHIVE software distribution.
BootstrapBefore configuring and compiling, developers must create the configure script and Makefile.in input files by running the GNU build tools. This procedure is performed by the bootstrap script, which must be run in the psrchive directory:
cd psrchive ./bootstrapIf you encounter problems during bootstrap, please ensure that your GNU autotools are up-to-date.
ConfigureAfter running bootstrap, the configure script is run to determine the system configuration and produce the Makefiles. If you plan to develop PSRCHIVE in parallel with the software maintained at Swinburne or the ATNF, then please read these important notes on choosing an installation directory. If the configure script fails, please refer to the Common Problems.
CompileIn the top-level build directory (psrchive in most simple cases), type make to compile and make install to copy all products to the install directory. A complete list of the standard make targets can be found in the Standard Targets for Users section of the GNU coding standards.
In addition to the standard make targets, the following targets have been defined in the main directories:
For instructions on how to compile the rest of the Swinburne software
repository, please refer to the
rest of the repository notes in switching
to GNU autotools.
Making additionsIf you haven't already done so, please review the rules of thumb outlined in the design philosophy.
New code is added to the Makefile.am file in the relevant sub-directory.
Choosing a sub-directorySub-directories of the GNU configured and built software tree are compiled in a specific order. Therefore, it is not possible to compile code that depends upon header files or libraries that are produced later in the list. The order in which the sub-directories are compiled is as follows:
Util/units Util/third Util/genutil Util/fft Util/fitsutil Util/tempo Util/pgutil Util/qtutil Base/Classes Base/Extensions Base/Formats Base/Applications More/General More/MEAL More/Timing More/Polarimetry More/Plotting More/Applications More/rhythm
Modifying Makefile.amThe syntax of the automake input file, Makefile.am, is fairly straight-forward. There are basically four main targets:
header files: are defined by the include_HEADERS macro. If you want your headers to be installed in sub-directories of the include/ directory, use the nobase prefix, e.g.
nobase_include_HEADERS = Pulsar/Archive.h model_profile.h
libraries: are defined by the lib_LTLIBRARIES. Only the main directories, utils, astro, and psrchive produce libraries that may be used during linking. The sub-directories produce convenience libraries. Therefore, their libraries are defined with the noinst prefix, e.g.
noinst_LTLIBRARIES = libunits.laNotice that the library is given the .la extenstion. This is used by libtool, which will place an appropriate extension on the output library, depending on the architecture and on usage of static or dynamic libraries.
In addition to defining the name of the library, it is also necessary to define its contents. This is done with the SOURCES suffix. For example:
libunits_la_SOURCES = Error.C HeapTracked.C ReferenceAble.CNote how the name of the library has been canonicalized.
executables: are divided into two categories. Programs listed in the bin_PROGRAMS macro are compiled and installed by default. Programs listed in the check_PROGRAMS are compiled only if the user types make check are are never installed. Only the program name is specifed in a PROGRAMS macro definition, e.g.
bin_PROGRAMS = psradd psredit pacThe source code that gets compiled into each program is specified as in the case of libraries, for example:
psradd_SOURCES = psradd.C psredit_SOURCES = psredit.C pac_SOURCES = pac.C
After modifying Makefile.am, simply type make. Automake will rebuild the Makefile automatically.
This should be enough information to get started. For further information, please refer to the automake documentation.