From f4d3b86f123ae764b8a977e0e3178d960e1cd44a Mon Sep 17 00:00:00 2001 From: David L Parkhurst Date: Thu, 28 May 2015 00:00:02 +0000 Subject: [PATCH] Working on phreeqc readme. git-svn-id: svn://136.177.114.72/svn_GW/phreeqc3/trunk@9733 1feff8c3-07ed-0310-ac33-dd36852eb9cd --- README.Phreeqc.TXT | 325 +++++++++++++++++++++++++++++++-------------- 1 file changed, 224 insertions(+), 101 deletions(-) diff --git a/README.Phreeqc.TXT b/README.Phreeqc.TXT index ee05947f..caf73fad 100644 --- a/README.Phreeqc.TXT +++ b/README.Phreeqc.TXT @@ -5,14 +5,12 @@ README.TXT A program for speciation, batch-reaction, one-dimensional transport, and inverse geochemical calculations -This file describes compilation of the batch version of PHREEQC version 3 for -Linux. No executable file is included. The distribution contains all files -necessary to configure and compile PHREEQC on any Unix operating system. - -Instructions for configuring, compiling, installing, executing, and testing -on Linux operating systems are provided below. After installation, see the -root or doc directory of the PHREEQC installation for summary information on -PHREEQC in phreeqc.txt and the new features and bug fixes in RELEASE.TXT. +This file describes three batch versions of PHREEQC for Windows and Linux: (1) A +Windows version with a compiled executable, (2) A Windows version that has source +code that can be compiled with Visual Studio solutions that are generated by CMake, +and (3) A Linux version with source code that can be compiled by a Makefile generated +by configure. For Linux, there is no version with an executable, and compilation is +required. No graphical user interface exists for Linux. (For Windows, a graphical user interface, PhreeqcI, is available at @@ -24,19 +22,24 @@ Notepad++ interface is available at http://www.hydrochemistry.eu/downl.html.) A. Distribution files B. Documentation - C. Extracting files (for Unix compilation) - D. Compiling, testing, installing - E. Running PHREEQC + C. Installing the Windows executable version + + D. Compiling, testing, installing for Linux + E. Compiling, testing, installing for Windows + F. Running PHREEQC F. Description of test cases G. Contacts ----------------------------------------------------------------------------------- -A. Distribution file +A. Distribution files ----------------------------------------------------------------------------------- - The following distribution package (containing the source code, configure - files, examples, and documentation) is available for Linux systems: - + The following distribution packages of the batch version of PHREEQC are available + for Windows and Linux: + +phreeqc-@VERSION@-@REVISION@.msi 64-bit batch version with executable + compiled by using Microsoft Visual C++ 2005 +phreeqc-@VERSION@-@REVISION@.zip For compilation on Windows phreeqc-@VERSION@-@REVISION@.tar.gz For compilation on Linux ----------------------------------------------------------------------------------- @@ -81,44 +84,137 @@ Charlton, S.R., and Parkhurst, D.L., 2002, PhreeqcI--A graphical user interface FS-031-02, 2 p. ----------------------------------------------------------------------------------- -C. Extracting files (for Unix compilation) +C. Installing the batch version of PHREEQC with executable ----------------------------------------------------------------------------------- -A compressed tar file, phreeqc-@VERSION@-@REVISION@.tar.gz, is used to -distribute the source code and other files necessary to compile, test, install, -and run PHREEQC on Unix operating systems. +Note: the person installing the software generally must have administrator +rights. -Follow the steps below to extract the files from a distribution tar -file. +To install the batch version, double-click phreeqc-@VERSION@-@REVISION@.msi to +execute the installation program and follow the directions on the screen. The batch +version is completely independent from the GUI version. + +----------------------------------------------------------------------------------- +D. Compiling and installing the Windows batch version of PHREEQC without executable +----------------------------------------------------------------------------------- - Steps in extracting files Explanation - ---------------------------------------- ----------------------------------- - gunzip phreeqc-@VERSION@-@REVISION@.source.tar.gz Uncompress the tar.gz file. +In general, to compile the IPhreeqc library, you will need: - tar -xvpof phreeqc-@VERSION@-@REVISION@.source.tar Extract files from the tar file. + (a) CMake (build process manager) + (b) a C++ compiler, + (c) familiarity with the compiler and the Windows operating system. + + +D.1. Download and install CMake -The directory phreeqc-@VERSION@-@REVISION@ is created when the files are -extracted; if this directory already exists, you may want to delete or rename -it before extracting the files. + CMake can be downloaded from http://www.cmake.org/. If you download the + executable, CMake is installed when you execute it. + +D.2. Unzip the distribution file phreeqc-@VERSION@-@REVISION@.zip + + The directory phreeqc-@VERSION@-@REVISION@ is created when the files are + extracted; if this directory already exists, you may want to delete or rename it + before extracting the files. -The following directory structure is created (the contents of each directory -are shown to the right): + The following directory structure is created (the contents of each directory are + shown to the right): - phreeqc-@VERSION@-@REVISION@ Files related to configure - `--config More configure files + phreeqc-@VERSION@-@REVISION@ Files related to CMake `--database Database files required during execution `--doc Documentation files `--examples Examples from user's guide--used in verification tests `--src Source code - `--test Files used to test the compilation + `--test Files used to test the compilation + +D.3. Generate a Visual Studio solution + + CMake has many options other than Visual Studio, but here we assume that you are + using some version of Visual Studio. On the first use of CMake, it may be + necessary to close all Visual Studio instances. + + Open CMake. + + Fill in the top two lines: + Where is the source code: + The top level directory (ie c:/iphreeqc-@VERSION@-@REVISION@). + Where to build the binaries: + A new directory. It is suggested that the name of the directory include + the characteristics of the library that is built, including the VS + version, 32/64 bit, dll/lib. for example, vs2012_64_dll. + + Click Configure. + From the pulldown menu select the 64-bit version for your Visual Studio. + Normally, the default radio button should be sufficient. Click Finish. + + Options in the top panel: + (1) CMAKE_INSTALL_PREFIX--Sets the the install directory where the + library and header files will be saved. It is suggested that + an INSTALL directory be defined inside the directory chosen + for the binaries. + + Click Configure until the screen is not red. If the screen remains red, you will + have to deal with the CMake error messages. + + Click Generate. + + You should now have a Visual Studio solution file (.sln) in the directory chosen + for the binaries (second line of CMake screen). At any point, you can delete the + contents of the directory and start over. You can make solutions for different + Visual Studios, or different options in other directories. + +D.4. Compile and install PHREEQC + + Open the Visual Studio solution in the build directory defined in CMake. + + The default configuration is "Debug". If you want a release libraries + (or dlls) and examples, change the configuration to "Release". + + Build ALL_BUILD. + IPhreeqc is compiled. + + Build RUN_TESTS. Programs that test IPhreeqc are compiled and run, and optionally + (CMake IPHREEQC_FORTRAN_TESTING option) the Fortran test project. + + + Build INSTALL. + + The libraries, header files, Fortran module source files, PHREEQC database + files, and documentation are installed in the install directory selected in + CMake. + + Install\library directory (lib or dll) may include: -Notes: (a) A compiled executable is not included in the source - distribution. - (b) It is recommended that no user files be kept in the PHREEQC - directory structure. - ------------------------------------------------------------------------------------ -D. Compiling, testing, installing + Install\Database files: + Amm.dat + frezchem.dat + iso.dat + llnl.dat + minteq.dat + minteq.v4.dat + phreeqc.dat + pitzer.dat + sit.dat + wateq4f.dat + + Install\doc files: + Phreeqc_3_2013_manual.pdf Manual for PHREEQC version 3 + Phreeqc_2_1999_manual.pdf Manual for PHREEQC version 2 + phreeqc.txt Short explanation for PHREEQC + RELEASE Release notes + README this readme file + NOTICE User rights notice + phreeqc3.chm Latest PHREEQC documentation + + + Install\examples files: + Input files for the 22 examples described in the version 3 manual + + Note: In order to use the CLR version (Charting) the Zedgraph.dll file + must be registered either by installing the Phreeqc or the PhreeqcI MSI, + or through the use of the Visual Studio Tool gacutil. + +----------------------------------------------------------------------------------- +E. Compiling and installing the Linux batch version of PHREEQC ----------------------------------------------------------------------------------- No support beyond this README file is provided for users compiling their own @@ -131,74 +227,98 @@ versions of the software. In general, to compile the software, you will need: A Makefile can be generated by configure, and the Makefile can be used to compile, test, and install the software. -To compile, test, and install PHREEQC, do the following: +E.1. Extracting the files -D.1. Change directory to the directory that was extracted from the tar file. + Follow the steps below to extract the files from a distribution tar file. - cd phreeqc-@VERSION@-@REVISION@ - -D.2. Make a directory, for example, Release. - - mkdir Release - -D.3. Change directory to Release. - - cd Release + Steps in extracting files Explanation + ---------------------------------------- ----------------------------------- + gunzip phreeqc-@VERSION@-@REVISION@.source.tar.gz Uncompress the tar.gz file. + + tar -xvpof phreeqc-@VERSION@-@REVISION@.source.tar Extract files from the tar file. -D.4. Run configure - - Many of the options for configure can be seen by typing: - - ../configure --help - - The most common option: - --prefix=dir specifies the directory for installation of the - library. Default is /usr/local, $HOME would install - to your home directory. + The directory phreeqc-@VERSION@-@REVISION@ is created when the files are + extracted; if this directory already exists, you may want to delete or rename it + before extracting the files. + + The following directory structure is created (the contents of each directory are + shown to the right): + + phreeqc-@VERSION@-@REVISION@ Files related to configure + `--config More configure files + `--database Database files required during execution + `--doc Documentation files + `--examples Examples from user's guide--used in verification tests + `--src Source code + `--test Files used to test the compilation + +Notes: (a) A compiled executable is not included in the source distribution. - Run configure as follows: - - ../configure [options] + (b) It is recommended that no user files be kept in the PHREEQC directory + structure. -D.5. Compile the program +E.2. Change directory to the directory that was extracted from the tar file. + + cd phreeqc-@VERSION@-@REVISION@ + +E.3. Make a directory, for example, Release. + + mkdir Release + +E.4. Change directory to Release. + + cd Release + +E.5. Run configure + + Many of the options for configure can be seen by typing: + + ../configure --help + + The most common option: --prefix=dir specifies the directory for installation of + the library. Default is /usr/local, $HOME would install to your home directory. + + Run configure as follows: + + ../configure [options] + +E.6. Compile the program make [-j 4] Optionally, use -j n--where n is the number of compilations make runs in parallel. -D.6. Check that compiled version runs the test cases. - Check may take several minutes. +E.7. Check that compiled version runs the test cases. + Check may take several minutes. - make check + make check - Results of running the test cases are stored in the directory - - Release/test + Results of running the test cases are stored in the directory Release/test -D.7. Install the program. - By default the program is installed in /usr/local/bin - and /usr/local/share/doc/phreeqc. You can specify an installation prefix - other than "/usr/local" by using the prefix option, prefix=$HOME for - example. +E.8. Install the program. + + By default the program is installed in /usr/local/bin and + /usr/local/share/doc/phreeqc. You can specify an installation prefix other than + "/usr/local" by using the prefix option, prefix=$HOME for example. - make install + make install - The locations of various files are given below, where "install" is the - installation directory, /usr/local by default, or the value given - by the --prefix option to configure. + The locations of various files are given below, where "install" is the + installation directory, /usr/local by default, or the value given by the --prefix + option to configure. - Executable: - install/bin/phreeqc + Executable: + install/bin/phreeqc - Documentation: + Documentation: - install/share/doc/phreeqc - Phreeqc_3_2013_manual.pdf Manual for Phreeqc version 3 - Phreeqc_2_1999_manual.pdf Manual for Phreeqc version 2 - phreeqc.txt Short explanation for Phreeqc - RELEASE Release notes - README this readme file - NOTICE User rights notice + install/share/doc/phreeqc + Phreeqc_3_2013_manual.pdf Manual for Phreeqc version 3 + Phreeqc_2_1999_manual.pdf Manual for Phreeqc version 2 + phreeqc.txt Short explanation for Phreeqc + RELEASE Release notes + README this readme file + NOTICE User rights notice ???phreeqc3.chm Databases: @@ -221,11 +341,11 @@ D.7. Install the program. Input files for 22 examples documented in the Phreeqc 3 manual ----------------------------------------------------------------------------------- -E. Running PHREEQC +F. Running PHREEQC ----------------------------------------------------------------------------------- If PHREEQC has been installed in a directory included in the users' PATH, the -program can be executed with any of the commands below. +program can be executed from a command line with any of the commands below. command to execute PHREEQC explanation ----------------------------- ----------------------------------------- @@ -248,16 +368,16 @@ program can be executed with any of the commands below. and screen output is directed to the file screen_output. -For Linux, if the "make install" command described above has not been -executed, the executable may be copied to the current directory. In addition -the default database file, phreeqc.dat, or another desired database may need -to be in the current directory. - -Databases are phreeqc-@VERSION@-@REVISION@/database and, if installed, -install/share/doc/phreeqc/database. +If phreeqc is not located in a directory in PATh, the executable may be copied to the +current directory. In addition the default database file, phreeqc.dat, or another +desired database may need to be in the current directory. The shell variable PHREEQC_DATABASE can be used to specify the default -database. In the C shell, this variable can be set (assuming your database +database. + +For Linux: + +In the C shell, this variable can be set (assuming your database is named /home/jdoe/local/project/mydata.dat) with the command: setenv PHREEQC_DATABASE /home/jdoe/local/project/mydata.dat @@ -269,7 +389,10 @@ In the Bourne or Korn shell, this variable can be set with the command: The shell variable can be set permanently by including the appropriate command in a file that is read when the shell is initiated, frequently $HOME/.login or $HOME/.profile. If this shell variable is not set, the default database is -assumed to be phreeqc.dat in the current directory. +assumed to be phreeqc.dat in the current directory. + +For Windows: +??? ----------------------------------------------------------------------------------- F. Description of test cases