From 1e2dbff92b0e2fcfd52738089100c95d41ba9b3b Mon Sep 17 00:00:00 2001 From: craig-warren Date: Mon, 30 May 2016 14:24:23 +0100 Subject: [PATCH] Revised installation procedure. Now the same for user and devs. No more hosting pre-built binary extensions, users build themselves. --- README.rst | 86 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 61 insertions(+), 25 deletions(-) diff --git a/README.rst b/README.rst index 47e807c1..c797b2ee 100644 --- a/README.rst +++ b/README.rst @@ -55,46 +55,82 @@ Package overview Installation ============ -You should use the following guidance to install gprMax if you are an end-user (i.e. you don't intend to develop or contribute to the software). Developers (or those intending to use gprMax in a HPC environment) should follow the Installation for developers section (http://docs.gprmax.com/en/latest/readme_install_devs.html#installation-for-developers). +The following steps provide guidance on how to install gprMax: -The steps are: +1. Install Python and required Python packages, and get the gprMax source code from GitHub +2. Install a C compiler which supports OpenMP +3. Build and install gprMax -1. Get the code -2. Install Python and required Python packages -3. (*Microsoft Windows only*) Install C libraries - -1. Get the code ---------------- - -* Download the code from https://github.com/gprMax/gprMax - - * Click on **Releases** from the top header and choose the release you want (latest is at the top). - * Download zip files of the **source code** and **binary extensions** for your platform (``windows-32bit`` for 32-bit or ``windows-64bit`` for 64-bit versions of Microsoft Windows, ``linux-64bit`` for 64-bit versions of Linux, or ``macosx-64bit`` for 64-bit versions of Mac OS X). - * Expand both zip files. - * Copy the contents (binary extensions) from the ``windows-32bit``, ``windows-64bit``, ``linux-64bit`` or ``macosx-64bit`` directory into the ``gprMax-v.X.Y.Z/gprMax`` directory. - -2. Install Python and required Python packages +1. Install Python and required Python packages ---------------------------------------------- We recommend using Miniconda to install Python and the required Python packages for gprMax in a self-contained Python environment. Miniconda is a mini version of Anaconda which is a completely free Python distribution (including for commercial use and redistribution). It includes more than 300 of the most popular Python packages for science, math, engineering, and data analysis. -* Install the Python 3.5 version of Miniconda for your platform from http://conda.pydata.org/miniconda.html (You can get help with installing Miniconda from http://conda.pydata.org/docs/install/quick.html) -* Open a Terminal (Linux/Mac OS X) or Command Prompt (Windows) and navigate into the top-level gprMax directory. -* Update conda :code:`conda update conda` -* Create an environment (using the supplied ``conda_env.yml`` environment file) for gprMax with all the necessary Python packages :code:`conda env create -f conda_env.yml` -* Activate the new environment :code:`source activate gprMax` (Linux/Mac OS X) or :code:`activate gprMax` (Windows). +* Install the Python 3.5 version of Miniconda for your platform from http://conda.pydata.org/miniconda.html (help is at http://conda.pydata.org/docs/install/quick.html) +* Open a Terminal (Linux/Mac OS X) or Command Prompt (Windows) and run the following commands: + * :code:`conda update conda` (to make sure conda is up-to-date) + * :code:`conda install git` + * :code:`git clone https://github.com/gprMax/gprMax.git` (to get the latest gprMax source code from GitHub) + * Go to the top-level gprMax directory and execute :code:`conda env create -f conda_env.yml` (this will create an environment for gprMax with all the necessary Python packages) + * Activate the new environment :code:`source activate gprMax` (Linux/Mac OS X) or :code:`activate gprMax` (Windows). .. note:: * When you are finished using gprMax the Miniconda environment can be deactivated using :code:`source deactivate` (Linux/Mac OS X) or :code:`deactivate` (Windows). * If you want to install Python and the required Python packages manually, i.e. without using Anaconda/Miniconda, look in the ``conda_env.yml`` file for a list of the requirements. -3. (*Microsoft Windows only*) Install C libraries -------------------------------------------------- +2. Install a C compiler which supports OpenMP +--------------------------------------------- -* Install the Microsoft Visual Studio 2015 C++ Redistributable (``vc_redist.x86.exe`` for 32-bit or ``vc_redist.x64.exe`` for 64-bit) from https://www.microsoft.com/en-us/download/details.aspx?id=48145. +Linux +^^^^^ + +* gcc (https://gcc.gnu.org) should be already installed, so no action is required. + + +Mac OS X +^^^^^^^^ + +* gcc (https://gcc.gnu.org) is easily installed using the Homebrew package manager (http://brew.sh) :code:`brew install gcc --without-multilib`. + +.. note:: + + Installations of Xcode on Mac OS X come with the LLVM (clang) compiler, but it does not currently support OpenMP, so you must install gcc. + + +Microsoft Windows +^^^^^^^^^^^^^^^^^ + +* Download and install Microsoft Visual C++ Build Tools 2015 directly from http://go.microsoft.com/fwlink/?LinkId=691126 or by going to https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx and choosing Visual Studio Downloads -> Tools for Visual Studio 2015 -> Microsoft Visual C++ Build Tools 2015. Install using the default options. + +3. Build and install gprMax +--------------------------- + +Once you have installed the aforementioned tools follow these steps to build and install gprMax: + +* Open a Terminal (Linux/Mac OS X) or Command Prompt (Windows), navigate into the top-level gprMax directory, and run the following commands: + * If it is not already active, activate the gprMax conda environment :code:`source activate gprMax` (Linux/Mac OS X) or :code:`activate gprMax` (Windows) + * :code:`python setup.py build` + * :code:`python setup.py install` + +.. note:: + + * You should see a set of :code:`.c` source files and a set of :code:`.so` (Linux/Mac OS X) or :code:`.pyd` (Windows) compiled module files inside the gprMax directory. + * If you want to remove/clean the built modules, e.g. before updating gprMax, you can use :code:`python setup.py cleanall`. **You are now ready to proceed to running gprMax.** + +Updating gprMax +=============== + +* Open a Terminal (Linux/Mac OS X) or Command Prompt (Windows), navigate into the top-level gprMax directory, and run the following commands: + * If it is not already active, activate the gprMax conda environment :code:`source activate gprMax` (Linux/Mac OS X) or :code:`activate gprMax` (Windows) + * :code:`git pull` (this will pull the most recent source code from GitHub) + * :code:`python setup.py cleanall` + * :code:`python setup.py build` + * :code:`python setup.py install` + + Running gprMax ==============