Windows source installation

Introduction

The following instructions detail how to create an environment for compiling ISSM from source under Windows. We rely on MSYS2 to provide a Linux-like interface and the MinGW compiler chain to generate native Windows executables and libraries. There may be other methods for achieving the above, which we invite you to share on the ISSM forum.

NOTE: You will have to use an Administrator user account for some of the following to work as intended

A Note About Anaconda

Anaconda environments can cause all sorts of toolchain conflicts at configuration and compile time that are hard to diagnose. If you use Anaconda and are having issues compiling the external packages, you might try disabling your Anaconda environment with,

conda deactivate

If you have an environment other than the default loaded, you can disable it with,

conda deactivate <ENV_NAME>

If disabling your Anaconda environment resolves configuration/compilation issues, you might consider disabling it by default in your shell profile (after the conda initialize block).

MATLAB

  • If not already installed, navigate to https://www.mathworks.com/downloads/web_downloads/select_release
  • Click the button corresponding to the latest version that is available
  • Click the 'Windows' button
  • Follow the prompts to download the package
  • When the download completes, open the package (which should extract its contents to a temporary location, then run the installer)
  • When prompted, enter the email and password associated with your MathWorks account
  • When prompted, select the license you would like to associate with this MATLAB installation
  • Select the default destination folder, or one of your choosing, and make note of it
  • In addition to 'MATLAB' and 'Simulink', check the box for 'Mapping Toolbox' (if you have a license for it)
  • Click the 'Install' button and grab a cup of coffee and/or continue to the next step

MSYS2

Install MSYS2

  • Navigate to https://www.msys2.org
  • Download the installer
  • When the download completes, run the installer
  • Use the default value for 'Installation Folder'
  • Use the default value for 'Start Menu shortcuts'
  • Deselect 'Run MSYS 64bit now' and click the 'Finish' button

Set up shortcut for MSYS2 terminal emulator

  • In the Windows 'Search Bar', search for "MSYS2"
  • The 'Best match' should be 'MSYS2 MSYS'; click 'Open file location'
  • In the resulting File Explorer window, right-click 'MSYS2 MinGW 64-bit' and select 'Send to' -> 'Desktop (create shortcut)'
  • Right-click on the newly-created desktop shortcut and select 'Properties'
    • click the 'Advanced...' button
    • check the box labeled 'Run as administrator'
    • click the 'OK' button
    • click the 'Apply' button
    • click the 'OK' button

Update the package database and install required packages

  • Double-click the 'MSYS2 MinGW 64-bit' desktop shortcut
  • At the resulting command prompt run,
    $ pacman -Syu
    to update the database and base packages, entering "Y" when prompted
  • The previous step will result in the window being closed, so double-click the 'MSYS2 MinGW 64-bit' desktop shortcut again
  • At the resulting command prompt run,
    $ pacman -Su
    until the resulting output is,
    :: Starting core system upgrade... there is nothing to do :: Starting full system upgrade... there is nothing to do
  • Install necessary packages with,
    $ pacman -S --needed base-devel git openssh python subversion unzip mingw-w64-x86_64-autotools mingw-w64-x86_64-cmake mingw-w64-x86_64-toolchain
    entering "Y" or simply hitting the return key as needed
  • (Optional) Install Vim text editor with,
    $ pacman -S vim

Shell profile

.bash_profile

  • Open /c/msys64/home/<user>/.bash_profile for editing (the easiest way to do this is with vim if you installed it in the previous step)
  • Add the following to the bottom of the file,
    # Allow for NTFS symbolic links export MSYS=winsymlinks:nativestrict

.bashrc

  • Open /c/msys64/home/<user>/.bashrc for editing and add the following at the bottom of the file,
    ## MATLAB # MATLAB_VER="<MATLAB_VER>" # Allows for easy resetting of MATLAB version added to path export MATLAB_PATH=$(cygpath -u $(cygpath -ms "/c/Program Files/MATLAB/${MATLAB_VER}")) export PATH="${MATLAB_PATH}/bin:${PATH}" ## ISSM # export ISSM_DIR=<ISSM_DIR> export ISSM_DIR_WIN=$(cygpath -ms "${ISSM_DIR}") # Needed by MATLAB
    where <MATLAB_VER> is the version of MATLAB that you have installed (for example, "R2023b") and <ISSM_DIR> is the path to your local copy of the ISSM source code repository (for example, /c/Users/<USER>/ISSM, where <USER> is your username)

Microsoft MPI

  • Navigate to https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi-release-notes
  • Click the link for 'Microsoft Download Center' that corresponds with the latest release (take note of the version number that you download for the next step; it can also be found by going to 'Settings' / 'Apps \& Features')
  • Click the 'Download' button
  • Make sure both boxes are checked, then click the 'Next' button
  • Click the 'Save File' button for each file
  • When the download completes, run each installer
  • Follow the prompts, using the default installation directories

External package installation

All ISSM external packages are located in the $ISSM_DIR/externalpackages/. Several packages may be installed depending on what users want to do. The following packages and installation scripts are recommended for a standard installation of ISSM on Linux,

msmpi install.sh petsc install-3.14-win-msys2-mingw-msmpi.sh triangle install-win-msys2-mingw.sh m1qn3 install.sh

NOTE: After the installation of each package, one should source the ISSM environment,

$ source $ISSM_DIR/etc/environment.sh

ISSM compilation

ISSM relies on autotools to make source code packages portable to many Unix-like systems. The last step consists of generating the Makefiles needed to compile ISSM. First, ISSM must be reconfigured,

$ cd $ISSM_DIR $ autoreconf -ivf

ISSM can then be configured. You need to create a configuration file called configure.sh and placed in $ISSM_DIR. Here is an example of configuration script for a Windows machine with the MATLAB interface.

NOTE:

  • MATLAB_PATH was defined previously in bashrc.
  • MSMPI_ROOT will be defined after running,
    $ source $ISSM_DIR/etc/environment.sh
    .
  • You may need to update the path to libgfortran in the -with-fortran-lib option.
./configure \ --prefix=${ISSM_DIR} \ --with-numthreads=4 \ --with-vendor="win-msys2" \ --with-matlab-dir=${MATLAB_PATH} \ --with-mpi-include="${MSMPI_ROOT}/include" \ --with-mpi-libdir="${MSMPI_ROOT}/lib" \ --with-mpi-libflags="-lmsmpi" \ --with-fortran-lib="-L/c/msys64/mingw64/lib/gcc/x86_64-w64-mingw32/10.2.0 -lgfortran" \ --with-metis-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-parmetis-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-blas-lapack-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-scalapack-dir="$ISSM_DIR/externalpackages/petsc/install" \ --with-mumps-dir="$ISSM_DIR/externalpackages/petsc/install" \ --with-petsc-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-triangle-dir="${ISSM_DIR}/externalpackages/triangle/install" \ --with-m1qn3-dir="${ISSM_DIR}/externalpackages/m1qn3/install"

If the configuration completed without any errors, ISSM can now be compiled,

$ cd $ISSM_DIR $ make $ make install

ISSM installation is done!

(Optional) SSHd

NOTE: The following is probably not applicable to most users.

  • Navigate to https://www.msys2.org/wiki/Setting-up-SSHd
  • Copy the contents of the code block and paste to a new text file
  • Set the value of the variable UNPRIV_NAME to the desired user
    • If the user does not already exist, it will be created
    • If the user does already exist, note the default password is the same that is used to log in to the Windows user account
  • Save the file out to the location of your choice
  • In a MSYS2 MinGW 64-bit shell instance, run the script
  • If errors occur with messages about missing packages, install those packages and run the script again
  • You can disregard the message,
    cygrunsrv: Error removing a service: OpenService: Win32 error 1060: The specified service does not exist as an installed service.
  • The following message indicates that setup was successful,
    The MSYS2 sshd service is starting. The MSYS2 sshd service was started successfully.
  • You can test that the service and your log in are working correctly by running,
    ssh -l <UNPRIV_NAME> localhost
    where <UNPRIV_NAME> is the same user that we authorized to use the service. You should be prompted to accept an ECDSA fingerprint, you which you respond "yes". Then, enter the password for this account. If all goes well, you should now have a prompt that reads,
    <UNPRIV_NAME>@<HOSTNAME> MSYS ~
  • Once logged in to the target machine, open /etc/ssh/sshd_config for editing, add,
    AcceptEnv MSYSTEM
    then save out the changes. On the client machine, open /etc/ssh/ssh_config for editing, add,
    SendEnv MSYSTEM
    to the file (you can add MSYSTEM to the list of environment variables if SendEnv already exists), then save out the changes. You can now prefix your SSH commands like,
    MSYSTEM=MINGW64 ssh [...]
    in order to log in to the MSYS2 MinGW 64-bit shell (other possible values are MSYS2 and MINGW32).
  • If an attempted SSH connection from a remote machine stalls out or is denied, it may be the case that you are running Windows Defender Firewall and need to open port 22. To do so,
    • in the Windows search bar, search for "Defender" and select 'Windows Defender Firewall with Advanced Security'
    • click 'Inbound Rules' in the left sidebar
    • click 'New Rule...' in the right sidebar
    • select 'Port', then click the 'Next' button
    • select 'TCP'
    • select 'Specific local ports', set the field to "22", then click the 'Next' button
    • select 'Allow the connection' then click the 'Next' button If you are using a third-party firewall application, it is up to you to determine how to open port 22.
    • uncheck the 'Public' box (if a subsequent attempted connection stalls out or is denied, you may need to edit this rule, checking the 'Public' box, but try first without it), then click the 'Next' button
    • set the 'Name' field to "SSH", then click the 'Next' button
  • The ssh-keygen utility can be used to create a more secure SSH connection and to protect your Windows user password
  • If you later decide that you want to stop the sshd service, you can do so with,
    net stop msys2_sshd
    and can remove the service altogether with,
    cygrunsrv -R msys2_sshd

Sources: