.. _get-and-compile-source:

===========================================================================
Tutorial 2: LSDTopoTools analysis driver: getting and compiling the program
===========================================================================

  `LSDTopoTools <http://www.geos.ed.ac.uk/~smudd/LSDTT_docs/html/>`_ is a collection
  of tools for the analysis of topographic and spatially distributed data developed 
  in the `University of Edinburgh <http://www.ed.ac.uk/home>`_ `School of GeoSciences <http://www.ed.ac.uk/schools-departments/geosciences/>`_.
  
  The code has been developed to conduct reproducible research in geomorphology, hydrology and ecology. 
  
  Most users will run the code using the program ``LSDTT_analysis_from_paramfile.out``.
  These tutorials focus on analysis using this program. 
  
Getting the source code  
=====================================================

Instructions for inexperienced linux users
--------------------------------------------

  If you know what you are doing in linux jump ahead to here :ref:`get-source-experienced`

  First, you have to get the source code. There is a vague plan to make binaries available, 
  but for the time being you will need to `compile <http://en.wikipedia.org/wiki/Compiler>`_ the code on your own Linux computer. 
  If you are in the University of Edinburgh's School of GeoSciences this should be relatively easy. 
    
  The code should theoretically run compile on both a Mac (it has a Linux backend) or Windows. 
  For Windows you'll need to download the gnu c++ compiler using `cygwin <https://www.cygwin.com/>`_. 
  However, we use Linux because that is the operating system on our servers at the University of Edinburgh, 
  and all of these instruction are specific to Linux. 
  
  If you do manage to compile these programs on Windows or MacOS email me (`Simon M. Mudd <http://www.geos.ed.ac.uk/homes/smudd>`_)
  and I'll post the tutorial on this website. 
  
    #. The first thing you want to do is open a terminal window: :ref:`getting-onto-servers`. 
    
    #. Now, using `cd` to change directories and `cd ..` to go up a directory, find somewhere to put the code.  
    
    #. Once you have found a good place to put your code, make a new directory for it using `mkdir`, for example::
    
        mkdir topographic_analysis   
      
    #. If you forgot what folder you are in, you can find it with the `pwd` command. Here is a typical sequence of commands:: 
    
        smudd@burn topographic_tools $ mkdir topographic_analysis
        smudd@burn topographic_tools $ cd topographic_analysis/
        smudd@burn topographic_analysis $ pwd
        /home/smudd/topographic_tools/topographic_analysis
        smudd@burn topographic_analysis $   
          
    #. Now you need to download the zipped source code. You do it like this:: 
    
        wget http://www.geos.ed.ac.uk/~smudd/LSDTopoToolbox_driver/LSDTT_analysis.zip  
        
    #. This will download the zipped code. If you type `ls` (to list files in your directory) you can see that the zipped code is there::
    
        smudd@burn topographic_analysis $ wget http://www.geos.ed.ac.uk/~smudd/LSDTopoToolbox_driver/LSDTT_analysis.zip
        --2014-09-25 13:12:50--  http://www.geos.ed.ac.uk/~smudd/LSDTopoToolbox_driver/LSDTT_analysis.zip
        Resolving www.geos.ed.ac.uk... 129.215.8.163
        Connecting to www.geos.ed.ac.uk|129.215.8.163|:80... connected.
        HTTP request sent, awaiting response... 200 OK
        Length: 321850 (314K) [application/zip]
        Saving to: `LSDTT_analysis.zip'
        
        100%[======================================>] 321,850     --.-K/s   in 0.006s  
        
        2014-09-25 13:12:50 (48.0 MB/s) - `LSDTT_analysis.zip' saved [321850/321850]
      
        smudd@burn topographic_analysis $ ls
        LSDTT_analysis.zip   
        
    #. You can now use the linux `unzip` command to unzip the source code::    
    
        unzip LSDTT_analysis.zip      
        
    #. It will quickly unzip everything. Now if you type `ls` you will see a bunch of new stuff:: 
    
        smudd@burn topographic_analysis $ ls
        analysis_driver        LSDIndexChannel.hpp                LSDRaster.hpp
        LSDAnalysisDriver.cpp  LSDIndexRaster.cpp                 LSDShapeTools.cpp
        LSDAnalysisDriver.hpp  LSDIndexRaster.hpp                 LSDShapeTools.hpp
        LSDChannel.cpp         LSDJunctionNetwork.cpp             LSDStatsTools.cpp
        LSDChannel.hpp         LSDJunctionNetwork.hpp             LSDStatsTools.hpp
        LSDFlowInfo.cpp        LSDMostLikelyPartitionsFinder.cpp  LSDTT_analysis.zip
        LSDFlowInfo.hpp        LSDMostLikelyPartitionsFinder.hpp  TNT
        LSDIndexChannel.cpp    LSDRaster.cpp
        smudd@burn topographic_analysis $     
        
    #. These are the source files. *Note* if you are at Edinburgh and you have access to your `T:\` or `M:\`  
       drives you could do all this stuff in Windows explorer. But you should get used to using the terminal so this
       is good practice. 

.. _get-source-experienced:

Instructions for experienced linux users
------------------------------------------------

  #. You will already have a terminal window open, because you feel cold and empty without one.
  
  #. Make a directory for the code. 
  
  #. Download it::
  
      wget http://www.geos.ed.ac.uk/~smudd/LSDTopoToolbox_driver/LSDTT_analysis.zip
    
  #. Unzip::
  
      unzip LSDTT_analysis.zip
    
  #. Move on to the next bit. 

Compiling the source code  
=========================================    

  Unzipping the source code created a directory called ``analysis driver``. Go into this directory::
  
    cd analysis_driver
    
  and run ``make``, by typing this::
  
    make -f Drive_analysis_from_paramfile.make
    
  You should now have a program called ``LSDTT_analysis_from_paramfile.out``.
  
  You are now ready to move on to the next step: performing your first analysis!