Merge branch 'master' of https://github.com/dmorse/pscf

CMakeLists.txt

@@ -13,6 +13,10 @@ project (PSCF)
 #### Based on https://cmake.org/Wiki/CMakeForFortranExamplea ####
 enable_language (Fortran)
 
+option(USE_FFT3 "Use the fft3_mod file (and FFT3.0). Otherwise, use fft2_mod (and FFTW2)" ON)
+option(USE_DEVEL "Use the -D DEVEL option with the Fortran preprocessor" ON)
+option(BUILD_DMG "Build a DMG based application for OSX clients" OFF)
+
 # Add our extra Find*.cmake modules
 LIST(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/tools/cmake/")
 
@@ -71,16 +75,21 @@ set(CPACK_PACKAGE_VERSION_PATCH "0")
 # TODO: build out components "applications libraries headers" (where headers are the .mod files)
 set(CPACK_COMPONENTS_ALL Unspecified)
 
-# TODO: finish Bundle 
-# TODO: finish DEB and RPM generators (http:https://www.vtk.org/Wiki/CMake:Component_Install_With_CPack)
+# DONE: finish Bundle 
+# DONE: finish DEB and RPM generators (http:https://www.vtk.org/Wiki/CMake:Component_Install_With_CPack)
 # TODO: finish NSIS generator (http:https://www.vtk.org/Wiki/CMake:Component_Install_With_CPack)
-# TODO: test compile and package on Unix and Windows
+# DONE: test compile and package on Unix and Windows
 if (APPLE)
- set(CPACK_GENERATOR 
- Bundle 
- TGZ
- ZIP
- )
+ if (BUILD_DMG)
+ set(CPACK_GENERATOR 
+ Bundle 
+ )
+ else (BUILD_DMG)
+ set(CPACK_GENERATOR 
+ TGZ
+ ZIP
+ )
+ endif (BUILD_DMG)
 else (APPLE)
  if (UNIX)
  if (EXISTS /etc/redhat-release)
@@ -89,12 +98,15 @@ else (APPLE)
  TGZ
  ZIP
  )
+ set(CPACK_RPM_PACKAGE_REQUIRES "lapack >= 3.0.0, libfft3 >= 3.2.0")
  else()
  set(CPACK_GENERATOR 
  DEB
  TGZ
  ZIP
  )
+ # TODO: verify these versions
+ set(CPACK_DEBIAN_PACKAGE_DEPENDS "liblapack3 (>= 3.0.0), libfftw3-3 (>= 3.3.0)")
  endif()
  else (UNIX)
  set(CPACK_GENERATOR 
@@ -122,7 +134,7 @@ set(CPACK_BINARY_DRAGNDROP ON)
 # This gives us a nice prompt to accept the license on OSX.
 set(CPACK_RESOURCE_FILE_LICENSE ${CMAKE_SOURCE_DIR}/LICENSE)
 
-#TODO: havent quite figured out how to include the README in the .app
+#DONE: havent quite figured out how to include the README in the .app
 set(CPACK_RESOURCE_FILE_README ${CMAKE_SOURCE_DIR}/README)
 set(CPACK_RESOURCE_FILE_WELCOME ${CMAKE_SOURCE_DIR}/README)
 set(CPACK_PACKAGE_DESCRIPTION_FILE ${CMAKE_SOURCE_DIR}/README)

README

@@ -27,53 +27,39 @@
 
  PSCF depends upon the FFTW fast Fourier transform library and the 
  LAPACK linear algebra library. These packages must be installed 
- before attempting to compile the program from source. Neither of
- these packages is needed to use a precompiled binary executable, 
- which is self-contained.
+ before attempting to compile the program from source.
 
------------------------------------------------------------------------
-Directory Structure
-
- src/ - Fortran 90 source files
- src/build - - directory containing Makefile
- examples/ - usage examples, with input files
- doc/ - documentation files
- doc/sphinx - - user manual text files
- doc/api - - auto-generated api documentation
- tools/ - Tools for processing output and source
- tools/matlab - - matlab m-files for visualization
- tools/python - - python scripts for data analysis
- tools/python/preprocess-0.6.1 - Forpedo preprocessor script
+ User Documentation:
 
- An annotated list of source files is provided in the file src/SRC_FILES. 
+ A web user manual is avalaible at:
 
-----------------------------------------------------------------------
-Documentation
+ https://pscf.readthedocs.org
 
-The source files for a user manual are easily readable text files that 
-are stored in the doc/user-man directory, The resulting web pages are 
-also available online at the site:
+ Instructions for compiling the program from source, as well as various
+ ways to install precompiled executables, are discussed in the user manual.
 
- https://pscf.readthedocs.org
+ The source files for the user manual are text files that are stored in 
+ the doc/user-man directory. The relevant files have file extension .rst. 
+ Installation instructions are given in doc/sphinx/install.rst
 
-Instructions for compiling the program from source, as well as various
-ways to install precompiled executables, are discussed in the file 
+-----------------------------------------------------------------------
+ Developer Documentation:
 
- doc/sphinx/install.rst
+ Developer API documentation may be generated by following instructions 
+ given in the file doc/README. The resulting .html page are installed in 
+ doc/devel-man.
 
-and in the corresponding section of the web user manual. 
+ Directory Structure
 
-Developer API documentation may be generated by following the 
-instructions given in the file doc/README, which are repeated in the
-user manual. The resulting .html page are installed in doc/devel-man.
+ src/ - Fortran 90 source files
+ doc/ - documentation files
+ doc/user-man - - user manual source files
+ tools/ - Tools for processing output and source
+ tools/matlab - - matlab scripts for visualization
+ tools/python - - python modules
 
+ An annotated list of source files is provided in the file src/SRC_FILES. 
+ Before modifying any fortran files, also see the note at the end of that
+ file regarding the use of preprocessor to generate some files.
 ----------------------------------------------------------------------
-Preprocessor Script
-
-Several of the fortran *.f source files have been created using a 
-python preprocessor from corresponding files that end with the suffix
-*.fp.f. This preprocessor script, named "Forpedo", is included with the 
-distribution. Before modifying any of the fortran source files, please 
-read the discussion of the preprocessor near the end of the file 
-src/SRC_FILES.
 

doc/user-man/binary.rst

@@ -0,0 +1,106 @@
+
+.. _install-binary-sec:
+
+Binary Installation
+===================
+
+The steps to install a precompiled binary are different for different operating
+systems, and somewhat different for different distributions of linux. The 
+intaller for Mac OS X installs a completely self-contained package that 
+includes copies of all required external libraries. Instructions for using
+.rpm and .deb installers for Redhat and Debian linux systems instead require 
+the user to install packages containing the FFTW fast Fourier transform and 
+Lapack linear algebra libraries before installing PSCF.
+
+Mac OSX
+-------
+
+The procedure for installing PSCF on a Mac using a binary installer is 
+similar to that for installing any application on a Mac:
+
+ * Download the Mac pscf<version>.dmg installer from the PSCF home page
+
+ * Open the .dmg file, and drag and drop the pscf_terminal icon file 
+ into the Applications folder.
+
+To run the program, simply double clicking the pscf_terminal application. 
+This will open up a yellow terminal window from which you can use standard 
+unix commands to navigate within the directory structure of your Mac, and 
+from which you can invoke the pscf command.
+
+The first time you attempt to run pscf_terminal, Mac OSX security settings 
+will prevent the application from starting because it is from an "Unknown 
+Developer". You will need to add an exception for this software. The 
+following instructions are provided by Apple on 
+https://support.apple.com/kb/PH18657?locale=en_US: 
+
+1. In the Finder, locate the app you want to open. Don’t use Launchpad to do 
+ this. Launchpad doesn’t allow you to access the shortcut menu.
+
+2. Press the Control key, then click the app icon, then choose Open from the 
+ shortcut menu.
+
+3. Click Open.
+
+The app is saved as an exception to your security settings, and you can 
+open it in the future by double-clicking it just as you can any registered 
+app.
+
+Ubuntu or Debian Linux
+----------------------
+
+Ubuntu and Debian distributions of the linux operating systems both use 
+package management systems that use .deb package files. To install on 
+Ubuntu:
+
+ * Download the pscf<version>.deb package from the PSCF home page
+
+ * Use the Ubuntu software center graphical installer or the apt-get
+ command line utility to install the following packages:
+
+ - libfftw3-3
+ - liblapack3
+
+ To install these packages using apt-get, enter::
+
+ sudo apt-get libfftw3-3
+ sudo apt-get liblapack3
+
+ * Install the pscf package by running::
+
+ dpkg -i pscf<version>.deb
+
+ * If the above command fails because of a missing dependence, try 
+ running::
+
+ apt-get install pscf<version>.deb
+
+ This allows apt-get to attempt to fetch any missing dependencies.
+
+
+Fedora / Redhat Linux
+---------------------
+
+Redhat distributions of the linux operating systems, including Fedora 
+and CentOS, use package management systems that use .rpm package files. 
+Instructions are similar to those for Ubuntu/Debian, except for the use 
+of a different package file format and package manager. In this case:
+
+ * Download the pscf<version>.rpm package from the PSCF home page
+
+ * Use the yum command line utility or the Fedora graphical package 
+ manager to install the following packages from the appropriate
+ Fedora repository:
+
+ - fftw
+ - lapack
+
+ To install these packages using yum from the command line, enter::
+
+ > sudo yum install lapack
+ > sudo yum install fftw
+
+ * To install, enter::
+
+ sudo rpm -Uvh pscf<version>.rpm
+