The apsim installer generation scripts all live in the apsim repository, inside the Setup/netcoreapp3.1 directory.
The Linux installer is really a Debian installer, as it is a .deb file which can only be (directly) installed by distributions using dpkg/apt. However, the .deb file may be unpacked with 7zip allowing any Linux user to run or repack the files as they desire. In the long run I'd like to see official installers for some of the other major distros, but we've never been asked for this and for now, people can either use custom builds, docker, or repacks of the debian installer. It's also worth noting that the package names in the installer dependencies are designed for and tested under Ubuntu.
The installer is built by a bash script located at ApsimX/Setup/netcoreapp3.1/debian/buildDebianInstaller. The script takes 2 arguments:
- Full version number (e.g. yyyy.MM.revision.0)
- (Optional) output file name. Default if not specified is apsim-$version.deb.
The only unusual dependency for running the script is the .net sdk (currently v3.1). The script is normally run in the apsiminitiative/apsimng-build docker image.
The built installer does not bundle any of apsim's libraries. Instead it relies on system libraries, as listed by the dependencies in the control file.
The windows installer is generated by Inno Setup. The config file can be found at ApsimX/Setup/netcoreapp3.1/windows/apsimx.iss. The installer may be built by installing InnoSetup and running iscc /path/to/apsimx.iss.
The installer file, when created as part of jenkins builds, is signed with a code-signing certificate obtained from CSIRO IM&T. The certificate is issued to CSIRO and will expire on April 10 2025. The certificate may be inspected by running something like openssl x509 -noout -text -in /path/to/certificate.crt.
The installer file may be run with or without administrator privileges. If run without admin, it will be unable to install apsim under C:\Program Files. Instead, it will default to installing apsim into %LOCALAPPDATA%. If run with admin privileges, it will default to installing under C:\Program Files.
The installer will check whether apsim dependencies are installed on the system before installing apsim:
- .NET Runtime: if the requried version is missing, setup will prompt the user to install it and will open a link to the appropriate download page. This must be updated whenever the target framework version used by apsim is changed. The is all set from within the apsimx.iss file.
- GTK: if the required version of the native gtk libraries is missing, the installer can automatically download and install them. This works by downloading a prepared bundle from the GtkSharp dependencies repository and extracting it to a suitable location. This must be updated whenever we update to a new version of GtkSharp which itself requires updated native libs.
The generated installer supports a few command-line options:
/upgradefrom <version>: Upgrade from the specified version. In other words, uninstall the specified version before proceeding with the installation. The path to the old version will be read from the registry. Failing to uninstall the previous version will cause a warning to be displayed, but will not cause the installation of the new version to fail. This functionality is implemented via a pascal script in apsimx.iss. This is used when performing an upgrade via the upgrade area of the apsim GUI.
/log: causes a log file to be created in the user's temp directory detailing file installation and [run] actions taken during the installation process. This is helpful for debugging problems with the installation process.
/log=<filename>: as above, but with a fixed path/filename.
More command-line options can be found here.
The MacOS installer is a .dmg file built automatically by jenkins.
The installer is built by a bash script in the apsim repository located at ApsimX/Setup/netcoreapp3.1/macos/buildMacInstaller. The script would typically be run on Linux, though in principle it could probably be run on MacOS. The script has a few dependencies of note:
- libdmg-hfsplus
- genisoimage
- .NET Sdk (currently v3.1)
Typically, the script would be run from within the apsiminitiative/apsimng-complete docker image, which contains all of the required dependencies.
The script takes 2 arguments:
- Full version number (e.g. yyyy.MM.$revision.0)
- (Optional) output filename - if not set, defaults to apsim-$version.dmg
The MacOS installer differs to the Debian and windows installers in that it bundles the required runtime dependencies with apsim itself, in order to avoid users needing to install gtk themselves via homebrew (normally gtk would be installed with homebrew: brew install gtk+3). Bundling these dependencies like this results in a much larger installer, but one that is (mostly) self-contained.
Bundling the .net runtime is actually the default behaviour of dotnet publish when publishing for a specific platform (-r osx-x64 in this case) when one does not specify --no-self-contained.
The gtk libraries are downloaded by the installer generator script from this repo, which contains a tarball of the dependencies compiled on a mac. These libraries were manually compiled from source. In theory it's quite easy to rebuild them (there's a script for doing so - see the instructions in the repo). In practice, the script often fails for arcane reasons, and even when it works, it takes several hours to run. So if you need to update the libraries - e.g. for a bugfix - then good luck. You'll need it.
Upon "running" the installer on a mac, users will normally be presented with a message saying that the application cannot be trusted. This can be overcome by first going to Settings -> Security & Privacy -> Allow apps downloaded from app store and identified developers. Then, right-click on the installer and select open (rather than double-clicking), and choose to trust the installer. All of this could be overcome if we were to join apple's developer program, which costs money.
The upgrade functionality on MacOS is implemented via a bash script in the apsim repository. This script will be run by the apsim when performing an upgrade from the GUI.