# ARG Package: Sasktran Core Components #
This package is used to build the C++ Sasktran Core Components and to create python installation wheels  as well as Matlab installation scripts. The SasktranIF API is available [online](http://arg.usask.ca/docs/SasktranIF/) while this page focuses on the build aspects.

Pre-compiled python wheels are supported on both Linux(x64) and Windows(x64). We have unreliable, untested and outdated support for Matlab installations running under Windows, needless to say we don't recommend its use. We make no attempt to support 32-bit platforms as many of the radiative transfer engines can exhaust the 4 GB memory limit available in 32 bit operating systems.

## Building the code on Windows ##
The code can be built using a Visual Studio 2015 Developer Command Window and running the batch file `buildarglibraries.bat` from the containing directory. The format of the command is one of,

- `buildarglibraries VS2015 Release x64` for Matlab support
- `buildarglibraries VS2015 Py36 x64` for python 3.6 support
- `buildarglibraries VS2015 Py35 x64` for python 3.5 support 
- `buildarglibraries VS2015 Py34 x64` for python 3.4 support

Compilation will take several minutes. If it fails then just run the whole process again as we do get the odd inter-project dependency causing the odd failure. It should only need a maximum of 2 or 3 re-runs otherwise there is another problem . After a successful build the python wheels will be created in sub-directory `PythonWheels` and the Matlab installation scripts will be in directory `MatlabInstallation`.

### (i) Build Dependencies ###
The compilation and linking is dependent upon third party libraries which are available as pre-compiled windows binaries from USASK-ARG at git@arggit.usask.ca:ThirdParty/PrebuiltWindowsLibs.git. You must set the macro or environment variable ARG_THIRDPARTY accordingly

The Boost C++ libraries are also required. Any version > 1.55 should work.
On Windows you can download the prebuilt Boost installer from here https://sourceforge.net/projects/boost/files/boost-binaries/1.62.0/ (Version 1.62 is tested and known to work)
download the version marked `msvc-14.0-64`.  After installing, add the following directories to your personal `Microsoft.Cpp.x64.User` Visual Studio 2015 property sheet: 


- Under VC++ Directories, Include Directories add: `PATH_TO_YOUR_BOOST_INSTALLATION`
- Under VC++ Directories, Library Directories add: `PATH_TO_YOUR_BOOST_INSTALLATION\lib64-msvc-14.0`

To access the property sheet, open any project in the Visual Studio VS2015 IDE and access the Property Manager tab (go to View -> Other Windows -> Property Manager). You only need to edit it for one project and it will be automatically used in all others.

### (ii) Build Macros ###
The compilation and linking refers to the following external environment variables or VS2015 macros, 

1. **ARG_THIRDPARTY**, e.g. `G:\software\ARG_ThirdParty\PrebuiltWindowsLibs\`
2. **ANACONDA_BASEDIR**, e.g. `C:\Anaconda3`
3. **MATLAB_MEX64_BASEDIR**, e.g. `C:\Program Files\MATLAB\R2014a\extern\`

Note **the trailing backslashes are important**. The macros can be set in `Microsoft.Cpp.x64.User`.

<<<<<<< HEAD
### (iii) Anaconda Python Environments ###  
Note that the build relies upon an Anaconda Python environment that matches the requested build. I.E. Anaconda has python environments Py36, Py35 and Py34 which are activated using `call activate Py35` etc. We dont support using `pyenv` within the build system at this time.
=======
### (iii) Anaconda Python Environments ###
Note that the build requires an Anaconda Python environment that matches the requested build. For example, for a Python 3.6 build, create an environment named py36 (`conda create --name py36 python=3.6`) and then activate it (`activate py36`) before running the build.
>>>>>>> 4adef62e4356c851074019d2be00f387f64cfd81

### (iv) Swig ###
The Windows build uses the [SWIG](http://www.swig.org/ "SWIG") compiler to generate python interfaces to the C++ code and the swig compiler must be on your ** PATH ** for the build to work. We use a MinGW version of SWIG running under MSYS and it seems to work well. 

### (v) Matlab ###
The Windows build may build Matlab code depending upon your option. You must have a recent version of Matlab on your system and you must set the environment variable or Macro MATLAB_MEX64_BASEDIR to indicate the directory where MATLAB has all of the external includes and linkage for matlab Mex files. 

To disable the MATLAB build, open `Repos_BaseCode\nxhdf\CompilerIDE\VSxxxx\nxhdfonyx.sln` and go to Build -> Configuration Manager. Select the appropriate Active Solution Platform (x64) and Active Solution Configuration (Release), then uncheck build for matlabswathreader.
    
## Building the code on Linux ##

The linux python wheel can be built from source code through executing the script,
```
./buildarglibrarieslinux -b <InstallDir> -i <ThirdPartyIncludeDir> -l <ThirdPartyLibDir> -p <pythonenvironment>
```
but you must build and install the pre-requisite third party libraries. Follow the instructions on https://arggit.usask.ca/ThirdParty/LinuxBuildScripts for more details. The installed third party libraries are placed in a directory such as ~/thirdparty and then

* `<ThirdPartyIncludeDir> = ~/thirdparty/include`
* `<ThirdPartyLibDir> = ~/thirdparty/lib`

The script supports the following command line options:

* **-b** `<installdir>`  : The installation folder.  Libraries and python wheels are placed in this folder, The default `~/localinstall`.
* **-i** `<includedirs>` : Directories of header files of third party software, colon separated list, default is `~/thirdparty/include/`.
* **-l** `<libdirs>`     : Directories of third party libraries, colon separated list, default is `~/thirdparty/lib/`.
* **-p** `<python_environment>` : Build the wheel using the specified python environment via `source activate <python_environment>`. The default is the current python environment.
* **-m** : Build a **manylinux** python wheel. You must be in a suitable Docker environment. The default will not build the manylinux wheel. 
* **-c** : clean the projects as they are built. Default is not to clean."
* **-g** : Build debug versions. Note this is not well tested and you may encounter issues. You should also ensure the project is clean"
* **-h** : print this list of commands and exit"

The script defaults are setup to work *as-is* on the Docker environment on lloyd.usask.ca. Login into lloyd.usask.ca using your credentials and then build the environment. For example, start the [docker environment](https://arggit.usask.ca/ThirdParty/LinuxBuildScripts/wikis/manylinux-build). and build the code. Here is an example to build the manylinux wheel for python 3.6
 
    > sudo docker run -v /media/users:/media/users -it arg-manylinux-build:v0.4 /bin/bash
    > mkdir sources
    > cd sources
    > git clone git@arggit.usask.ca:ARGPackages/SasktranCoreComponents.git
    > cd SasktranCoreComponents
    > ./buildarglibrarieslinux -m -p py36


### (i) Build Dependencies ###
All of the packages in https://arggit.usask.ca/ThirdParty/LinuxBuildScripts are
required to be installed, and the associated dependencies mentioned on that page.
In addition, SasktranCoreComponents requires `boost` and `swig` to be installed.
On ubuntu, both of these can be installed with

```
apt install libboost-all-dev swig
```

`swig` is required to be version >= 3, it's version can be checked through,

```
swig -version
```