Update some installation-related docs

- Add comments for installation-related variables in CMake, in
  particular the RPATH section that has caused some confusion.
- Document those few variables that can be used to alter the
  installation tree structure in the install guide.
- Reword some parts in the install guide about CMake iteration.
- Remove GMX_INSTALL_PREFIX, as there are other approaches to get the
  desired result with CPack that are less confusing.  This variable
  wasn't documented or probably used anywhere outside some dormant
  Jenkins jobs.

Change-Id: I199b06d905b45961313ed9fa44ae82e5987be0fe

diff --git a/CMakeLists.txt b/CMakeLists.txt
index bc4ef86bfd8eec1b20f1f825414a2d2e9a9ee89e..b5f2ecce19fafd5c436afddad912f78aa18687e1 100644 (file)
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -103,9 +103,6 @@ if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT AND UNIX)
     set(CMAKE_INSTALL_PREFIX "/usr/local/gromacs" CACHE STRING "Installation prefix (installation will need write permissions here)" FORCE)
 endif()
 
-set(GMX_INSTALL_PREFIX "" CACHE STRING "Prefix gets appended to CMAKE_INSTALL_PREFIX. For cpack it sets the root folder of the archive.")
-mark_as_advanced(GMX_INSTALL_PREFIX)
-
 include(gmxBuildTypeReference)
 include(gmxBuildTypeTSAN)
 include(gmxBuildTypeASAN)
@@ -792,21 +789,26 @@ set(PKG_CFLAGS "${PKG_CFLAGS} ${OpenMP_C_FLAGS}")
 ########################################################################
 # Specify install locations
 ########################################################################
-# Use GNUInstallDirst to set paths on multiarch systems
+# Use GNUInstallDirs to set paths on multiarch systems.
 include(GNUInstallDirs)
 
+# Customization for the installation tree paths.
 set(GMX_LIB_INSTALL_DIR ${CMAKE_INSTALL_LIBDIR} CACHE STRING
     "Library installation directory (default: ${CMAKE_INSTALL_LIBDIR})")
 set(GMX_DATA_INSTALL_DIR gromacs CACHE STRING
     "Data installation directory under share/ (default: gromacs)")
 mark_as_advanced(GMX_LIB_INSTALL_DIR GMX_DATA_INSTALL_DIR)
 
-set(LIB_INSTALL_DIR  ${GMX_INSTALL_PREFIX}${GMX_LIB_INSTALL_DIR})
-set(BIN_INSTALL_DIR  ${GMX_INSTALL_PREFIX}bin)
-set(DATA_INSTALL_DIR ${GMX_INSTALL_PREFIX}share/${GMX_DATA_INSTALL_DIR})
-set(MAN_INSTALL_DIR  ${GMX_INSTALL_PREFIX}share/man)
-set(INCL_INSTALL_DIR ${GMX_INSTALL_PREFIX}include)
+# These variables are used internally to provide a central location for
+# customizing the install locations.
+set(LIB_INSTALL_DIR  ${GMX_LIB_INSTALL_DIR})
+set(BIN_INSTALL_DIR  bin)
+set(DATA_INSTALL_DIR share/${GMX_DATA_INSTALL_DIR})
+set(MAN_INSTALL_DIR  share/man)
+set(INCL_INSTALL_DIR include)
 
+# These variables get written into config.h for use in finding the data
+# directories.
 set(GMXLIB_SEARCH_DIR share/${GMX_DATA_INSTALL_DIR}/top)
 set(GMXLIB_FALLBACK   ${CMAKE_INSTALL_PREFIX}/${DATA_INSTALL_DIR}/top)
 
@@ -814,12 +816,22 @@ set(GMXLIB_FALLBACK   ${CMAKE_INSTALL_PREFIX}/${DATA_INSTALL_DIR}/top)
 include(gmxManageSuffixes)
 
 ################################################################
-# Shared library settings
+# Shared library load path settings
 ################################################################
-if((NOT CMAKE_SYSTEM_NAME STREQUAL "Darwin") OR ((CMAKE_SYSTEM_VERSION VERSION_GREATER 8.0) AND (NOT CMAKE_VERSION VERSION_LESS 2.8.12)))
+# CMake supports RPATH on OS X only from 2.8.12 upwards.
+# CMAKE_SYSTEM_VERSION > 8.0 matches OS X 10.5 and above, where RPATH support
+# was added.
+if((NOT CMAKE_SYSTEM_NAME STREQUAL "Darwin") OR
+   ((CMAKE_SYSTEM_VERSION VERSION_GREATER 8.0) AND (NOT CMAKE_VERSION VERSION_LESS 2.8.12)))
+    # The build folder always has bin/ and lib/; if we are also going to
+    # install to lib/, then the installation RPATH works also in the build
+    # tree.  This makes installation slightly faster (no need to rewrite the
+    # RPATHs), and makes the binaries in the build tree relocatable.
     if(GMX_LIB_INSTALL_DIR STREQUAL "lib")
         set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
     endif()
+    # Set the RPATH as relative to the executable location to make the
+    # binaries relocatable.
     if(NOT CMAKE_SYSTEM_NAME STREQUAL "Darwin")
         set(CMAKE_INSTALL_RPATH "\$ORIGIN/../${GMX_LIB_INSTALL_DIR}")
     else()
@@ -828,11 +840,13 @@ if((NOT CMAKE_SYSTEM_NAME STREQUAL "Darwin") OR ((CMAKE_SYSTEM_VERSION VERSION_G
     set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
     set(CMAKE_MACOSX_RPATH 1)
 else()
-    # We are on Darwin/OSX, and cmake cannot handle proper RPATHs
-    if(CMAKE_SYSTEM_VERSION VERSION_GREATER 8.0) #rpath supported for >10.4
+    # We are on Darwin/OSX, and CMake cannot handle RPATHs automatically.
+    if(CMAKE_SYSTEM_VERSION VERSION_GREATER 8.0)
+        # Set the RPATH options manually.
         set(CMAKE_INSTALL_NAME_DIR "@rpath")
         set(GMX_EXE_LINKER_FLAGS ${GMX_EXE_LINKER_FLAGS} "-Wl,-rpath,@executable_path/../${GMX_LIB_INSTALL_DIR}")
     else()
+        # Use the old INSTALL_NAME_DIR mechanism if RPATH is not supported.
         set(CMAKE_INSTALL_NAME_DIR "${CMAKE_INSTALL_PREFIX}/${LIB_INSTALL_DIR}")
     endif()
 endif()

diff --git a/install-guide/install-guide.md b/install-guide/install-guide.md
index 2b19bcf0dfda9d9e0a20187698b826680e4be7da..d780c6be2f8c556da49fc7fa21d2b9075fdd2bc4 100644 (file)
--- a/install-guide/install-guide.md
+++ b/install-guide/install-guide.md
@@ -360,9 +360,8 @@ general advice on what you are seeing and how to navigate and change
 things. The settings you might normally want to change are already
 presented. You may make changes, then re-configure (using `c`), so that it
 gets a chance to make changes that depend on yours and perform more
-checking. This might require several configuration stages when you are
-using `ccmake` - when you are using `cmake` the
-iteration is done behind the scenes.
+checking. It may take several configuration passes to reach the desired
+configuration, in particular if you need to resolve errors.
 
 A key thing to consider here is the setting of
 `CMAKE_INSTALL_PREFIX`. You will need to be able to write to this
@@ -374,9 +373,11 @@ home directory for your GROMACS installation. Even if you do have
 super-user privileges, you should use them only for the installation
 phase, and never for configuring, building, or running GROMACS!
 
-When `cmake` or `ccmake` have completed iterating, the
-cache is stable and a build tree can be generated, with `g` in
-`ccmake` or automatically with `cmake`.
+When you have reached the desired configuration with `ccmake`, the
+build system can be generated by pressing `g`.  This requires that the previous
+configuration pass did not reveal any additional settings (if it did, you need
+to configure once more with `c`).  With `cmake`, the build system is generated
+after each pass that does not produce errors.
 
 You cannot attempt to change compilers after the initial run of
 `cmake`. If you need to change, clean up, and start again.
@@ -633,6 +634,36 @@ programs and libraries, one might specify:
 Thus the names of all programs and libraries will be appended with
 `_mod`.
 
+### Changing installation tree structure ###
+
+By default, a few different directories under `CMAKE_INSTALL_PREFIX` are used
+when when GROMACS is installed. Some of these can be changed, which is mainly
+useful for packaging GROMACS for various distributions. The directories are
+listed below, with additional notes about some of them. Unless otherwise noted,
+the directories can be renamed by editing the installation paths in the main
+CMakeLists.txt.
+
+`bin/`
+  : The standard location for executables, some scripts, and some symlinks.
+    Some of the scripts hardcode the absolute installation prefix, which needs
+    to be changed if the scripts are relocated.
+`include/gromacs/`
+  : The standard location for installed headers.
+`lib/`
+  : The standard location for libraries. The default depends on the system, and
+    is determined by CMake.
+    The name of the directory can be changed using `GMX_LIB_INSTALL_DIR` CMake
+    variable.
+`share/gromacs/`
+  : Various data files and some documentation go here.
+    The `gromacs` part can be changed using `GMX_DATA_INSTALL_DIR`. Using this
+    CMake variable is the preferred way of changing the installation path for
+    `share/gromacs/top/`, since the path to this directory is built into
+    `libgromacs` as well as some scripts, both as a relative and as an absolute
+    path (the latter as a fallback if everything else fails).
+`share/man/`
+  : Installed man pages go here.
+
 ## Building GROMACS ##
 
 Once you have configured with `cmake`, you can build GROMACS. It is