Merge remote-tracking branch 'upstream/master'

CMakeLists.txt

@@ -107,6 +107,8 @@ else (APPLE)
  )
  # TODO: verify these versions
  set(CPACK_DEBIAN_PACKAGE_DEPENDS "liblapack3 (>= 3.0.0), libfftw3-3 (>= 3.3.0)")
+ # Default installation to /usr/local/bin on Ubuntu
+ set(CPACK_PACKAGING_INSTALL_PREFIX "/usr/local")
  endif()
  else (UNIX)
  set(CPACK_GENERATOR 
@@ -139,18 +141,18 @@ 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)
 
-if (APPLE)
+if (APPLE AND BUILD_DMG)
 # Force the README up to the DMG root 
 INSTALL(FILES ${CMAKE_SOURCE_DIR}/README DESTINATION ../../../Extra RENAME README.txt)
 INSTALL(FILES ${CMAKE_SOURCE_DIR}/LICENSE DESTINATION ../../../Extra RENAME LICENSE.txt)
 INSTALL(FILES ${CMAKE_SOURCE_DIR}/tools/bundle/HOWTO_INSTALL_OSX.txt DESTINATION ../../../. RENAME HOWTO_INSTALL_OSX.txt)
-else (APPLE)
+else (APPLE AND BUILD_DMG)
 INSTALL(FILES ${CMAKE_SOURCE_DIR}/README DESTINATION share/pscf RENAME README.txt)
 INSTALL(FILES ${CMAKE_SOURCE_DIR}/LICENSE DESTINATION share/pscf RENAME LICENSE.txt)
-endif (APPLE)
+endif (APPLE AND BUILD_DMG)
 
 install(PROGRAMS 
- tools/bin/pscf-read-outfile tools/bin/pscf-read-sweep
+ tools/bin/pscf-read-outfile tools/bin/pscf-read-sweep tools/bin/pscf-env
  DESTINATION bin)
 
 #INSTALL(DIRECTORY ${CMAKE_SOURCE_DIR}/tools/bin DESTINATION .)

README

@@ -2,7 +2,6 @@
 -----------------------------------------------------------------------
  PSCF - Polymer Self-Consistent Field Theory
  Copyright (2007-2016) Regents of the University of Minnesota
- Contact: David Morse, [email protected]
 
  PSCF is a Fortran 90 program for numerically solving the polymer 
  self-consistent field theory for periodic microstructures formed 
@@ -57,6 +56,7 @@
  tools/ - Tools for processing output and source
  tools/matlab - - matlab scripts for visualization
  tools/python - - python modules
+ make/ - build directory for make
 
  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

doc/Makefile

@@ -3,7 +3,7 @@
 # GDOC = path to GDoc.py python documentation generation script
 
 SRC=../src
-BUILD=$(SRC)/build
+BLD=../bld
 PYTHON=python
 GDOC=../tools/python/GDoc/GDoc.py
 
@@ -18,9 +18,9 @@ user-man:
 .PHONY: devel-man 
 
 devel-man: 
- cp $(BUILD)/pscf_pd.f $(SRC)/pscf_pd.f
- cp $(BUILD)/scf_mod.f $(SRC)/scf/scf_mod.f
- cp $(BUILD)/iterate_mod.f $(SRC)/iterate/iterate_mod.f
+ cp $(BLD)/pscf_pd.f $(SRC)/pscf_pd.f
+ cp $(BLD)/scf_mod.f $(SRC)/scf/scf_mod.f
+ cp $(BLD)/iterate_mod.f $(SRC)/iterate/iterate_mod.f
  $(PYTHON) $(GDOC)
  rm $(SRC)/pscf_pd.f
  rm $(SRC)/scf/scf_mod.f

doc/README

@@ -22,58 +22,12 @@ part of this package. To generate html api documentation:
 
  > make clean
 
- This will remove the entire doc/api subdirectory.
+ This will remove the entire doc/devel-man subdirectory.
 
-Re-Generating Developer API Documentation
------------------------------------------
+Re-Generating the User Manual
+-----------------------------
 
  To generate a local copy of the user manual, enter::
 
  > make user-man
 
-
-Preprocessor Generated Fortran Files
-------------------------------------
-
-The source code includes several *.f fortran files that generated 
-from corresponding *.fp.f preprocessor input files by a preprocessor. 
-In the current version of the code, the relevant fortran files are:
-
- src/build/scf_pd.f 
- src/build/iterate_mod.f 
- src/build/scf_mod.f
-
-Up-to-date copies of these three files must exist in the src/build
-directory before documentation can be built. Copies of these files
-are included in the initial distribution, but can be removed by the
-"very_clean" target of the src/build/Makefile. (So don't issue the 
-command "make very_clean" unless this is what you want!). They are
-not removed by the "make clean" command. 
-
-The above fortran files are generated from the following preprocessor 
-input files:
-
- src/scf_pd.fp.f
- src/iterate/iterate_mod.fp.f 
- src/scf/scf_mod.fp.f
-
-If you modify any of these *.fp.f files, or remove the corresponding
-*.f files from the src/build directory, and then use the Makefile in
-src/build directory to re-compile the program, new versions of these 
-files will be generated by the preprocessor and deposited in the 
-src/build directory. This action is dictated by the definition of 
-the corresponding *.f targets in src/build/Makefile, which list the
-*.fp.f preprocessor files as dependencies for the *.f fortran files,
-and by the the fact that the *.f fortran files are listed as 
-dependences for the corresponding *.o targets for these three files.
-
-The "devel-man" target of the documentation Makefile in the doc directory 
-first temporarily copies these three *.f programs from scr/build to 
-appropriate locations in the directory tree, each in the same directory 
-as the corresponding *.fp.f source file, then builds the html 
-documentation, and ends by removes these temporary copies of the 
-*.f files. (Read the devel-man target of the Makefile if this is 
-not clear). The directory structure of the api documentation, which 
-mimics the structure of the src directory, is thus constructed as 
-if each compilable *.f fortran were in the directory that contains 
-the corresponding *.fp.f preprocessor input file.

doc/user-man/compile-cmake.rst

@@ -220,13 +220,13 @@ required command is thus::
 
 Obtaining the Source Code
 -------------------------
-We assume in what follows that you will use cmake to implement on "out-of-source" build, in which all of the files generated during compilation are placed in a different directory than the source code. To begin, we suggest that you create a directory named pscf/ with a subdirectory named build/, by entering::
+We assume in what follows that you will use cmake to implement on "out-of-source" build, in which all of the files generated during compilation are placed in a different directory than the source code. To begin, we suggest that you create a directory named pscf/ with a subdirectory named cmake/, by entering::
 
  mkdir pscf
  cd pscf
  mkdir build
 
-The source code will be placed in another subdirectory of pscf/ which we will call repo/ (for repository).
+The source code will be placed in another subdirectory of pscf/ which we will call git/ (for repository).
 
 The source code for pscf is stored in a repository on the github.com server, at:
 
@@ -249,10 +249,10 @@ To download a zip file:
  * Move the pscf-master/ directory into the pscf/ directory that you
  just created.
 
- * Rename the pscf/pscf-master/ directory as repo/, by changing directory
+ * Rename the pscf/pscf-master/ directory as git/, by changing directory
  to pscf and then entering::
 
- mv pscf-master repo
+ mv pscf-master git
 
 To use git to clone the repository, after git is installed on your machine:
 
@@ -264,42 +264,142 @@ To use git to clone the repository, after git is installed on your machine:
 
  * This should create a subdirectory of pscf/ that is also named pscf/. 
  To avoid confusion, we recommend that you change the subdirectory 
- name to pscf/repo/, exactly as described above for the case of a 
+ name to pscf/git/, exactly as described above for the case of a 
  directory created from a zip file. 
 
 At this point, by either method, you should have pscf/ directory structure::
 
  pscf/
- build/
- repo/
-
-in which the build/ subdirectory is empty and the repo/ subdirectory 
-contains the source code obtained from the github repository.
+ cmake/
+ git/
+
+in which the cmake/ subdirectory is empty and the git/ subdirectory contains 
+the contents of github repository, including the source code.
+
+Choosing an Install Directory
+-----------------------------
+
+After installing all dependencies and obtaining the source code, you are
+ready to compile PSCF. 
+
+Before compiling the code, you need to decide where you would like to install 
+the pscf executable, along with several executable scripts, python modules, 
+and matlab files. The build system created by cmake will install these files 
+in subdirectories of a directory that we will refer to as the install directory. 
+Specifically, it will install the pscf executable and several executable scripts 
+in the bin/ subdirectory of the install directory, install python modules and
+matlab scripts in different subdirectories of the lib/ subdirectory, and install 
+several text files in the share/ subdirectory. After installation, the install 
+directory, denoted below by install/, will thus contain three subdirectories::
+
+ install/
+ bin/
+ lib/
+ share/
+
+The build system will create these three subdirectories if they do not 
+already exist. The default choice for the install directory is the system
+/usr/local directory, which is a standard location on linux for a system 
+administrator to install 'local' software on linux that is not part of the 
+linux distribution.
+
+We suggest that you consider the following three possible locations for the
+install directory for pscf:
+
+ * The pscf/ directory, which also contains the source code. 
+
+ * A standard installation directory within your user directory.
+
+ * The system /usr/local directory (the default).
+
+The advantage of the first two options is that both of them install all 
+of the software within your user directory tree, and thus do not require
+adminstrative privileges. The further logistical advantage of the first 
+option (installing within pscf/) is that it keeps all of the files in a 
+single directory tree within your user directory that only contains files 
+associated with pscf/, which makes it particularly easy to erase everything 
+and start over if desired. 
+
+The disadvantage of the first and second options, which both install files 
+within your user directory, is that both of them will require that you
+modify some operating system environment variables in order to conveniently
+use pscf. Specifically, if you install files in non-standard locations, you
+you will need to modify the PATH and PYTHONPATH environment variable thats
+allow the operating system and the python interpreter, respectively, to 
+find executable files and python modules when referrerd to by file name.
+Conversely, the advantage of installing in the /usr/local directory is
+that doing so causes executable files and python modules to be placed in
+standard locations where they will be found automatically.
+
+The only advantage of the second option (installation in a standard 
+location within your user directory tree) relative to the first is that, 
+if you plan to install multiple software packages from source and install 
+all of them in this location, you can configure your enviroment to always 
+look in appropriate subdirectories of this user directory for files, so
+that you do not need to further modify environment variables every time 
+you install new software within your user directory tree. If you choose 
+this option, it is conventional on some versions of linux to install 
+software in a hidden subdirectory of you home directory named ".local".
+We recommend this practice whether you are using linux or using the unix
+command line interface of Mac OS X. Note the dot in the beginning of 
+the name ".local", which makes it a hidden directory that will not show 
+up when you use "ls" to list files and directories in home directory, 
+unless you add the "-a" option, as "ls -a", to show hidden files and 
+directories. Installing in this location will cause the creation of 
+a tree of subdirectories of your private ${HOME}/.local directory that 
+is analogous to the structure of the /usr/local directory.
 
 Compiling and Installing
 ------------------------
 
-Before attempting to compile, you must follow the above instructions to
-create all dependencies, create an appropriate directory tree and obtain
-the source code. 
+As the first step of compiling and installing, change directory to the 
+pscf/cmake/ directory. Then make sure the cmake/ directory is empty 
+(removing all contents if necessary) and, from there, enter::
+
+ > cmake -DCMAKE_INSTALL_PREFIX=/path/to/install ../git
+
+In this command, the string "/path/to/install" denotes the path to
+the root of the install directory. The last argument "../git" is the
+relative path to your copy of the source code repository from the 
+pscf/cmake directory. 
+
+To install in the pscf/ directory tree, you would thus enter::
+
+ > cmake -DCMAKE_INSTALL_PREFIX=.. ../git
+
+where ".." represents the parent pscf/ directory. This will cause the 
+creation of bin/, lib/ and share/ subdirectories of the pscf/ directory, 
+alongside cmake/ and git/. 
+
+To install in the .local subdirectory of your home directory, instead
+enter::
 
+ > cmake -DCMAKE_INSTALL_PREFIX=~/.local ../git
 
-To compile and install, change directory to the pscf/build/ directory 
-and, from there, enter::
+in which the tilde (~) is linux shortand for the users home directory.
+
+Finally, to install in the /usr/local directory, you need adminstrator
+privileges on your machine, and would enter::
+
+ > sudo cmake ../git
+
+In this case, you must use the "sudo" command to apply the command 
+with "super-user" or administrator privileges, and you will be prompted 
+for your password. No -DCMAKE_INSTALL_PREFIX=" option is required in 
+this case /usr/local is the default installation location.
+
+The cmake command described above should create several subdirectories of 
+the pscf/cmake/ directory, which will contain files with instructions for 
+building pscf. To finish compiling and installing, simply enter::
 
- > cmake -DCMAKE_INSTALL_PREFIX=/path/to/install ../repo
  > make -j 4
  > make install 
 
-In the "cmake" command, the string "/path/to/install" is the root of 
-path used for installation. The last argument "../pscf". If you use 
-"-DCMAKE_INSTALL_PREFIX=.", the executable and other files that you 
-generate will be installed in tree rooted at the build directory 
-(e.g., pscf-build). The final pscf executable is self-contained and 
-can be copied to wherever you want after it is created.
-
-Wherever you install the executable file, you will need to make sure that 
-directory containing the executable (or a symlink to the executable) is 
-in the bash PATH variable, so that the operating system can find the 
-executable when it is invoked by name.
+from the pscf/cmake directory. 
+
+
+After the "make install" finishes execution, you can check that your chosen 
+install directory contains subdirectories named bin/, lib/ and share/, and 
+that the the bin/ subdirectory contains an executable file named pscf, along 
+with several executable scripts whose names begin with the suffix "pscf-...".