-
Notifications
You must be signed in to change notification settings - Fork 31
MatlabBinaries
The toolbox can be used within a Matlab environment or as a stand-alone app.
To run the toolbox as a stand-alone app, please see our installation instructions.
The guide below is a description of why we need such binaries and how they are created.
The imos-toolbox is distributed both in library form (all code sources) and as a stand-alone matlab app. The process of creating a stand-alone app is what we call creating a Matlab binary. The stand-alone app is currently distributed together with the source code and is available in the Github repo.
The app need to be created for individual architectures - currently only Linux and Windows - and is generated every time a new official/tagedd version is released (see the https://github.com/aodn/imos-toolbox/releases). Here and elsewhere we refer to these Binaries as the imos-toolbox app, and/or stand-alone binary.
The creation of the stand-alone apps or requires compilation/packaging. For that, we use the Matlab compiler (mcc), which is included as a Matlab toolbox (matlab compiler toolbox). Hence, both MATLAB, the matlab compiler toolbox, and other libraries are required. This is so because the stand-alone app needs all graphical libraries, java connectors (e.g. databases), and related source code in a single executable file.
The building/packaging will also recompiles by default the Java interface responsible for database communication and queries. Hence, a java development library is required. Updating of the Java connectors is not strictly necessary at every release unless one is doing a major/breaking release update (e.g. update of the runtime or Matlab versions).
Currently, the stand-alone app is compiled with Matlab runtime v95, which is compatible with Matlab R2018b.
The script to build the binaries - build.py - supports the following platforms:
- Windows 64bit
- Linux 64bit
- Matlab R2018b
- The Matlab compiler toolbox
- the statistics toolbox
- the image processing toolbox
- the signal processing toolbox
- Java Runtime Environment (Windows/Linux)
- ant-1.10.5+
- java-1.8.0_221+
- Git 2.22+
- Python 3.6+ and extra libraries installed via
pip(docopt,boto3,botocore,gitPython).
The current development uses OpenJDK (1.8.0_252) in Linux and the Oracle JRE 1.8.0_221 in Windows. Note that ant is part of the JRE in both platforms.
These java packages are required for rebuilding the java components - mostly the ddb.jar interface - which is used to talk with several databases. Note that building this jar is usually only required when these components are changed or when matlab (or the MCR) is updated. This jar is also cross-platform, so you should be able to build on Linux (windows) and use the same files in windows (Linux).
The binary is created by executing the build.py within the toolbox root folder. You will need to provide an architecture flag.
You may need to configure some environment variables so the script can easily find your MATLAB folders and the matlab compiler. For example, you may need to add the Matlab bin folder (which contains mcc) to your path. Check the toolbox installation instructions section. Otherwise, the build script also accept some file-path arguments. See build.py --help.
Assuming your path is configured correctly, the binary build is accomplished with a simple call in linux:
cd imos-toolbox
./build.py --arch=glnxa64In windows 10, this is also very similar and usually need to be executed within a cmdline.exe session:
cd imos-toolbox
build.py --arch=win64
The script is very verbose and will output some git status, the Matlab compiler (mcc) call, and other information. Please note that it will also overwrite by default the binary at the root folder of the toolbox.
The matlab compiler will do some checks for all files packaged into the stand-alone app. This includes a syntax checker and if some functions are missing.
Files with the wrong syntax will abort the compiler. Missing functions, however, will not and a binary file may be created with incomplete sources, which will trigger missing library bugs.