Merge pull request #175 from glenco/nt/travis-dependencies

improved handling of binary dependencies and documentation for releases

.travis.yml

@@ -5,9 +5,6 @@ compiler:
 os:
 - linux
 - osx
-env:
-- MULTINEST=3.8
-- MULTINEST=3.9
 notifications:
   email: false
 branches:
@@ -26,11 +23,7 @@ before_install:
   fi
 - pushd /tmp &&
   git clone git://github.com/JohannesBuchner/MultiNest.git &&
-  cd MultiNest &&
-  if [ "$MULTINEST" == "3.9" ]; then
-    curl -L http://git.io/vk01k | patch -p1;
-  fi &&
-  cd build &&
+  cd MultiNest/build &&
   cmake .. -G "Unix Makefiles" &&
   make &&
   sudo make install &&
@@ -44,15 +37,25 @@ script:
 - make test
 before_deploy:
 - export RELEASE_VERSION=$(git describe --tags)
-- export RELEASE_TAG=$TRAVIS_OS_NAME.multinest-$MULTINEST
+- export RELEASE_TAG=$TRAVIS_OS_NAME
 - export RELEASE=build/lensed-$RELEASE_VERSION.$RELEASE_TAG.tar.gz
 - if [ "$TRAVIS_OS_NAME" = "linux" ]; then
-    export CFITSIO_LIB="/usr/lib/x86_64-linux-gnu/libcfitsio.a";
-    export EXTRA_LIBS="/usr/lib/x86_64-linux-gnu/libz.a";
+    export CFITSIO_LIB="-l:libcfitsio.a";
+    export EXTRA_LIBS="-lz -Wl,-rpath='$ORIGIN'";
   fi
 - if [ "$TRAVIS_OS_NAME" = "osx" ]; then
     export CFITSIO_LIB="/usr/local/lib/libcfitsio.a";
+    export EXTRA_LIBS="-Wl,-rpath,@executable_path";
   fi
+- pushd /tmp &&
+  cd MultiNest &&
+  curl -L http://git.io/vkACf | patch -p1 &&
+  cd build &&
+  cmake .. -DCMAKE_MACOSX_RPATH=ON &&
+  make &&
+  sudo make install &&
+  if [ "$TRAVIS_OS_NAME" = "linux" ]; then sudo ldconfig; fi &&
+  popd
 - make distclean
 - make
 - make release

Makefile

@@ -264,7 +264,7 @@ RELEASE_FILES = \
 
 # release version from git
 ifndef RELEASE_VERSION
-RELEASE_VERSION = $(shell git describe --tags)
+RELEASE_VERSION = release
 endif
 
 # release tag

README.md

@@ -15,50 +15,72 @@ that was broken. Contributions in the form of new models are most welcome if
 they are generally useful.
 
 
-Setup
------
+Installation
+------------
+
+Pre-compiled binary distributions of Lensed are available for the official
+release versions, found on [GitHub](https://github.com/glenco/lensed/releases).
+More information can be found in the [documentation](docs/releases.md).
+
+There are a number of ways to get source distributions of the code, please see
+the [documentation](docs/building.md).
 
-There are a number of dependencies for Lensed (see docs/dependencies.md). Once
-they are satisfied and installed into the system, it should be possible to run
-or compile Lensed.
 
-If you are building Lensed from source, is typically enough to run
+Building
+--------
+
+Lensed is a simple Makefile project. If all dependencies are satisfied and
+installed into the system, it should be possible to compile Lensed by simply
+calling
 
     $ make
 
-in the root of the source directory, and the code should start compiling.
+from the root of the source directory. For further information, please refer to
+the [documentation](docs/building.md).
 
 
 Usage
 -----
 
-The most common way to invoke Lensed is to create a configuration file (see
-docs/configuration.md) which contains both the program options and the model
-that is being reconstructed. In this case, the reconstruction is started using
+The usual invocation of Lensed is with a [configuration](docs/configuration.md)
+file which contains program options and the model that is being reconstructed.
+The reconstruction is started using
 
     $ lensed config.ini
 
-where `config.ini` is the name of the parameter file.
+where `config.ini` is the name of the configuration file.
 
-It is possible to split the configuration into different configuration files,
-in order to e.g. modularise options and individual aspects of the model. For
-example, the following command would run Lensed with the configuration taken
-from three different files:
+It is possible to split the configuration into different files, for example to
+modularise options and individual aspects of the model. The following command
+would run Lensed with the configuration taken from three different files:
 
     $ lensed options.ini lens.ini sources.ini
 
 Repeated options are overwritten by the later configuration files.
 
-Finally, it is possible to give all of the options of a configuration file
-directly on the command line. For example, in order to change the number of
-live points for a quick look at results, one could invoke Lensed in the
-following way:
+Finally, it is possible to give any of the options (but not the model) directly
+on the command line. For example, in order to change the number of live points
+for a quick look at results, one could invoke Lensed in the following way:
 
     $ lensed config.ini --nlive=50
 
 As before, the order of the given configuration files and options is important.
 
-For more information on how to run Lensed, see the [documentation].
+
+License
+-------
+
+The Lensed source code can be freely modified and distributed under the terms
+of the [MIT license](LICENSE.txt). The authors also kindly ask that any and all
+scientific work which benefits from this software cites the relevant articles.
+
+This software makes use of the following libraries from third parties:
+
+-   MultiNest, copyrighted by Farhan Feroz and Mike Hobson, with some
+    limitations (especially for commercial use)
+-   CFITSIO
+
+Please see the [licenses file](docs/licenses.md) for copyright information.
 
 
 Versions

docs/building.md

@@ -1,5 +1,5 @@
-Building Lensed
-===============
+Building from source
+====================
 
 Lensed is a standard Makefile project. On a system where all dependencies can
 be resolved automatically, it should be enough to call
@@ -9,7 +9,7 @@ $ make
 ```
 
 from the root folder of Lensed to build the program. If this fails, further
-[configuration](#configuration) might be necessary.
+[configuration of the build system](#build-configuration) might be necessary.
 
 After compilation has finished, a quick check of
 
@@ -21,8 +21,84 @@ lensed X.Y.Z
 should display the correct version number of Lensed.
 
 
-Configuration
--------------
+Getting the sources
+-------------------
+
+### Releases
+
+Sources are available for each release of Lensed. These can be downloaded from
+the [releases page](https://github.com/glenco/lensed/releases). For details on
+releases, see the [corresponding page](releases.md).
+
+
+### Using Git
+
+Lensed is developed using the [Git version control system](https://git-scm.com)
+and [hosted on GitHub](https://github.com/glenco/lensed). Use Git to get the
+most recent development version of the code, especially if you plan on taking
+part in extending the code or fixing bugs.
+
+With Git installed on your system, use
+
+```sh
+$ git clone https://github.com/glenco/lensed.git
+```
+
+to clone the most recent version of the code into a subfolder of the current
+directory.
+
+There is a lot of information available about Git. For a first introduction,
+please [refer to the documentation](https://git-scm.com/doc), especially the
+first two chapters on [getting started](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control)
+and the [Git basics](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository).
+A quick introduction can also be found in the [Git tutorial](http://git-scm.com/docs/gittutorial).
+
+
+### From an archive
+
+On systems where no Git client is available, it is alternatively possible to
+get the latest development version of the sources in the form of an archive.
+A link is provided at the [project page](https://github.com/glenco/lensed).
+
+When working in a terminal environment, it is possible to download and extract
+Lensed using a combination of cURL and tar with the following command:
+
+```sh
+$ curl -L https://github.com/glenco/lensed/archive/master.tar.gz | tar -xz
+```
+
+Alternatively, if `curl` is not available, you can try to use `wget` instead:
+
+```sh
+$ wget https://github.com/glenco/lensed/archive/master.tar.gz
+$ tar -xzf master.tar.gz
+```
+
+Finally, if `tar` is not available you can replace the `.tar.gz` extension by
+`.zip`, and try the `unzip` command.
+
+Please note that using this method to get Lensed, it will not be possible to
+commit your changes or bug fixes back into the code base. Use of this method is
+therefore discouraged for normal development work, and only intended for the
+distribution of the code to "difficult" environments.
+
+
+Dependencies
+------------
+
+Building from source requires a number of dependencies to be met, namely
+
+-   MultiNest >= 3.8 ,
+-   CFITSIO 3 ,
+-   OpenCL headers and runtime library .
+
+If these dependencies are installed in a system-wide, default-accessible path,
+Lensed should be able to find them without any further intervention. For more
+information, refer to the [dependencies page](dependencies.md).
+
+
+Build configuration
+-------------------
 
 There are a number of configuration variables that can be passed to Lensed's
 build system. They are given in the form of `NAME="value"` pairs to `make`,
@@ -69,16 +145,15 @@ OPENCL_LIB = -framework OpenCL
 EXTRA_LIBS = 
 ```
 
-Please note that the `_INCLUDE_DIR` and `_LIB_DIR` variables override the value
-of the corresponding `_DIR` variable, so either the former two or the latter
-should be set.
+Please note that the `XYZ_INCLUDE_DIR` and `XYZ_LIB_DIR` variables override the
+value of the corresponding `XYZ_DIR` variable, so either the former two or the
+latter should be set.
 
 The following sections contain further details on configuring the individual
 components of Lensed.
 
 
-CFITSIO
--------
+### CFITSIO
 
 If CFITSIO has been built from source, the path to the source folder can be
 given to Lensed using the `CFITSIO_DIR` variable.
@@ -106,8 +181,7 @@ $ make CFITSIO_LIB="$HOME/libraries/my-cfitsio-lib.a"
 ```
 
 
-MultiNest
----------
+### MultiNest
 
 In case MultiNest was built using CMake, it is usually enough to pass the path
 to the source folder to make using the `MULTINEST_DIR` variable.
@@ -144,14 +218,18 @@ $ make MULTINEST_INCLUDE_DIR="/path/to/multinest/example_eggbox_C" \
 ```
 
 
-OpenCL
-------
+### OpenCL
+
+*
+**Mac OS X**: Please note that Mac OS X comes with a framework containing the
+OpenCL headers and library. It is not necessary to change the OpenCL settings.
+*
 
 In order to build Lensed, the compiler needs the OpenCL header `CL/cl.h` and
 the OpenCL runtime library.
 
-If these are provided by a vendor SDK, it is usually enough to point the
-`OPENCL_DIR` variable to the root of the SDK:
+If these are provided by a vendor SDK, it can be enough to set the `OPENCL_DIR`
+variable to the root of the SDK:
 
 ```sh
 $ make OPENCL_DIR="/usr/local/cuda"
@@ -174,6 +252,3 @@ This can be a linker flag such as `-lOpenCL` or an explicit path to a library.
 ```sh
 $ make OPENCL_LIB="$HOME/experimental-driver/libOpenCL.so"
 ```
-
-**Mac OS X**: Please note that Mac OS X comes with a framework containing the
-OpenCL headers and library. It is not necessary to change the OpenCL settings.

docs/dependencies.md

@@ -1,10 +1,10 @@
 Dependencies
 ============
 
-Lensed has a number of dependencies, namely
+Lensed has a number of compile-time dependencies, namely
 
--   [CFITSIO 3.370](#cfitsio) ,
--   [MultiNest 3.9](#multinest) ,
+-   [CFITSIO 3](#cfitsio) ,
+-   [MultiNest >= 3.8](#multinest) ,
 -   [OpenCL](#opencl) .
 
 If these dependencies are installed in a system-wide, default-accessible path,
@@ -17,14 +17,19 @@ CFITSIO
 The [CFITSIO](http://heasarc.gsfc.nasa.gov/docs/software/fitsio/) library is
 the standard for reading and writing FITS files.
 
+Binary releases are statically linked against a recent version of CFITSIO and
+therefore do not depend on it. When building from source, it is necessary to
+have both the CFITSIO library and the header files available.
+
 
 ### Packages
 
 Because CFITSIO is a mature library, pre-compiled binary versions are often
 found in the repositories of package management systems. If it is possible to
 install new packages into the system, this is the easiest way to get CFITSIO.
 
-**Ubuntu Linux**
+
+#### Ubuntu Linux
 
 For running a binary release, it should suffice to install the CFITSIO runtime:
 
@@ -38,7 +43,8 @@ When building Lensed from source, the CFITSIO development package must be used:
 $ sudo apt-get install libcfitsio3-dev
 ```
 
-**Mac OS X (Homebrew)**
+
+#### Mac OS X (Homebrew)
 
 The CFITSIO library can be found in the default Homebrew repository.
 
@@ -147,11 +153,15 @@ Lensed was designed from the start for heterogeneous computing environments,
 using [OpenCL](https://www.khronos.org/opencl/) to communicate with both CPU
 and GPU devices through a unified programming platform.
 
-A OpenCL runtime library for the compute devices present in the system. When
+A OpenCL runtime library for the compute devices must present in the system.
+Such a library usually comes with the driver of an OpenCL-enabled device. When
 building Lensed from source, it is further necessary to have the OpenCL headers
 installed.
 
-**Ubuntu Linux**
+
+### Packages
+
+#### Ubuntu Linux
 
 For the OpenCL runtime library, it is necessary to install the device drivers
 for the CPUs/GPUs present in the system. Please refer to the Ubuntu manual for
@@ -164,7 +174,7 @@ The OpenCL headers necessary for compiling Lensed can be found in package
 $ sudo apt-get install opencl-headers
 ```
 
-**Linux (general)**
+#### Linux (general)
 
 The device vendors usually provide Linux drivers and SDKs for their platforms.
 Some useful links are
@@ -173,7 +183,7 @@ Some useful links are
 -   [AMD APP SDK](http://developer.amd.com/tools-and-sdks/opencl-zone/amd-accelerated-parallel-processing-app-sdk/) ,
 -   [Nvidia OpenCL](https://developer.nvidia.com/opencl) .
 
-**Mac OS X**
+#### Mac OS X
 
 Mac OS X ships with the libraries and headers required to build OpenCL programs
 by default.