9  Portable applications

9.1 How does it work?

Kompanion is intended to be used as a portable environment with almost all batteries included. Applications are placed under .kompanion/bin/ directory and all configuration of paths and other required environment variables are provided by kompanion.ps1 script.

It mostly revolves around VS Code. You launch the editor through a dedicated script and everything else is available in its terminal. That said, the whole of the ecosystem is command line based - but this is scientific computing, if you don’t know command line you are in the wrong job. If you followed the instructions to source Kompanion from $PROFILE, then you can also launch the terminal from the start menu and everything will be available there as well.

It is intended to leave minimal track on host system (probably a few files and directories on your user home directory or under AppData), but this is not enforced in its development, so take care if you are not allowed to execute some software in a given computer.

9.2 Other possibly supported applications

The following packages are not currently included in Kompanion, but they are known to be somewhat portable and they might be added in the future. Those displayed in italics cannot be currently automated, but they can be installed in a machine then copied to Kompanion (ongoing investigation on how to automate that). Also check the Chapter 8 for a software selection that might be of interest for you and maybe not listed here.

• DualSPHysics
• Dyssol
• Fiji
• FileZilla
• FreeFEM++
• gnuplot
• Graphviz
• iperf
• Ipopt
• Jamovi
• JASP
• lazarus
• lite-xl
• LAMMPS
• MFiX
• MSYS2
• MUSEN
• Notepad++
• Octave
• OpenCALPHAD
• OpenModelica
• Orange3
• Portable LISP
• puTTy
• Ruby
• Rufus (requires admin privileges to be used though)
• SALOME (needs to be manually downloaded)
• Scilab
• strawberry-perl
• VMD
• ZeroBraneStudio
• Zettlr
• Xpra

9.3 Software specific instructions

9.3.1 DualSPHysics

For DualSPHysics one might also want to install this FreeCAD addon and this Blender addon.

9.3.2 gmsh

Because it was chosen that SDK version of gmsh was more adapted to integrate Kompanion, if you want to be able to pin the executable to your taskbar you need to copy the DLL from its lib/ directory to bin/. If you think you will not need Python/Julia interfaces of gmsh, then you can move the DLL instead to save ~80MB of disk (and you can always install gmsh with pip for those cases).

9.3.3 Graphviz

If the first time you run dot you get a message as

There is no layout engine support for "dot"
Perhaps "dot -c" needs to be run (with installer's privileges) to register the plugins?

Simply run dot -c as suggested and it should work fine (without admin privileges).

9.3.4 MFiX

This package is installed in a separate environment and not added to the toolbox path; that is because other Python environments could interact with each other and lead to unpredictable behavior. The following instructions are provided:

• Install miniforge3 under a dedicated directory.

• Add a script with the following content to launch miniforge console:

%windir%\system32\cmd.exe "/K" ^
    %~dp0\miniforge3\Scripts\activate.bat ^
    %~dp0\miniforge3

• Go to the downloads page, login and copy the personal installation command that looks like the following:

conda create -n mfix-<version> ^
    mfix==<version>            ^
    mfix-doc==<version>        ^
    mfix-gui==<version>        ^
    mfix-solver==<version>     ^
    mfix-src==<version>        ^
    -c conda-forge -c          ^
    https://mfix.netl.doe.gov/s3/<personal-token>//conda/dist

• To run the software activate the created environment and call its executable:

conda activate mfix-<version>
mfix

9.4 Creating a portable environment

This section illustrates the generalities of how do create a portable software toolbox. Before proceding with any installation, make sure to read all the elements provided below; simply trying to follow instructions in a step-by-step fashion will certainly lead to failure and frustration.

For each of the applications you will install, make sure to perform the following generic steps:

1. Download the portable version of the application, generally a .zip compressed file, and save it to some temporary location. Sometimes the normal installer of an application already supports portable mode.

2. Extract the compressed file to a dedicated directory. From there, you can move the content to the final location. See the notes below for details about compression practices.

3. Configure the application in a dedicated script or add a routine to the application script that manages all the paths and settings. The latter approach is recommended for putting everything together and is how Kompanion currently works.

Important: You need to be aware that there are two common practices of compressing (zip) a portable software: (1) some editors place everything in a directory and compress the directory, while others (2) pack everything under the root of the compressed file. Windows built-in system allows your to navigate compressed files as part of the filesystem, so inspect which of the above methods was used. If the later is detected, take care to select the right option to ensure the contents are extracted to a new directory. Several packages are stored directly at zip root and that may be messy to clean if extracted without the above precautions.

Important: since setting up the environment may require editing batch scripts, be aware that to open them you cannot click the file, but right-click and edit, as Windows see these as executables. In these files, lines starting by @REM are seem as comments and generally explain something about what follow them. If you are starting from scratch and do not master batch scripting, prefer learning PowerShell instead, as it is more modern and powerful, and you can easily call PowerShell scripts from batch scripts. It is how the current version of Kompanion is implemented and it is the recommended way to go.

9.4.1 Initial setup

These are the required steps to get your system working for the first time:

1. Go to VS Code download page and get the .zip version for x64 system (Arm64 is not supported here). Extract it to the binaries directory and copy the path of VS Code directory the set the variable VSCODE_DIR.

2. Go to Git download page and select 64-bit Git for Windows Portable, download it. Notice that this is not a compressed file per se, but it is desguised as an executable. Double-click it and accept the default PortableGit installation directory. After extraction finishes, move it to binaries directory. Add it to the path by setting the variable GIT_DIR to the path of the directory.

Important: After installing VS Code, do NOT enable its portable mode because the VBS file for launching it will point to a specific user-data folder.

Important: these notes are quite general and skip details. Refer to kompanion.ps1 and look for the functions Invoke-Configure* and Invoke-Install* for the exact steps to configure each application.

9.4.2 Programming languages

The following provides instructions for some languages you might wish to have fully integrated to your environment. For lower level languages, please consider using MSYS2 as described in its dedicated section.

9.4.2.1 Python

Go to WinPython download page and find the latest version tagged with a Latest green flag (avoid Pre-release versions on top). Expand the Assets and download the .exe version (also a disguised compressed file). Follow steps similar to Git above. See Invoke-ConfigurePython in kompanion.ps1 for the configuration of paths and environment variables.

9.4.2.2 Julia

Go to Julia download page and select the latest stable Windows 64-bit portable version. See Invoke-ConfigureJulia in kompanion.ps1 for the configuration of paths and environment variables.

Download rustup-init following the installation. See Invoke-ConfigureRust in kompanion.ps1 for the configuration of paths and environment variables.

9.4.2.3 Octave

Go to Octave download page and identify the .zip package for w64. As the main use of Octave is through its user interface, you can extract the content directly to bin/octave.

9.4.2.4 Ruby

Go to Ruby download page and identify the Devkit package for x64. During installation change the path to point to binaries and unselect the options to associate extensions and adding to the path.

9.4.2.5 LISP

LISP may be installed through Portacle. Instead of right-clicking and installing the executable, Shift-click and select to extract the contents; place the resulting portacle directory. You may choose not to add it to the path if using through its EMACs interface.

9.4.2.6 LaTeX and related

Although LaTeX is not mandatory, it is highly encouraged; otherwise, what is the point of doing any scientific computing and not publishing its results?

• Start by following the instructions provided here to install MikTeX. Point the installation to a directory miktex-portable under apps and select on-the-fly installation of new packages.

• Consider installing the following additional software:

  • JabRef
  • pandoc
  • inkscape

• Globally install pip install Pygments for enabling syntax highlight in LaTeX using minted; that is the most flexible highlighting method for adding code snippets to your documents.

• Also consider installing extension LaTeX Workshop for automatic compilation in editor with built-in PDF visualization.

To append to TEXMF variable one can use the MiKTeX Console graphical interface and under Settings > Directories navigate and select the local path.

If you prefer a dedicated LaTeX editor, you may wish to install texstudio; some configuration of paths with the application may be required as it is not directly integrated to this environment.

Warning: for now having both Rust and Octave fully operational in command-line is not working. This should not be a problem as Octave can be launched with its user-interface and that remain the most popular/recommended way of using it.

Warning: For a fully operational Jupyter notebook environment, other the LaTeX support discussed in its dedicatet section, you also need both pandoc and inkscape.

Important: It is strongly recommended to install Quarto as a supporting tool for publishing reports from Julia and Python.

9.4.3 MSYS2

MSYS2 environment is useful for developing native Windows applications and programming in languages as C, C++, Fortran, and Rust. Kompanion VS Code configuration will automatically include this environment to its available terminal lists, what might fail if you do not install it. To get it working do the following:

• Go to MSYS2 page and save the installer to downloads.

• Run the installer and change installation path to point to a local msys64 directory instead of the default C:/msys64 (requiring admin rights).

• Once finished, launch an UCRT64 environment as proposed in the installation guide. Install at least the following:

pacman -S \
    mingw-w64-ucrt-x86_64-toolchain \
    mingw-w64-ucrt-x86_64-binutils \
    mingw-w64-ucrt-x86_64-gcc \
    mingw-w64-ucrt-x86_64-gcc-fortran

• Full package list is provided here.

9.5 Creating a portable launcher

A simple way to create a portable launcher requiring to source extra variables is by writing a simple batch script exporting or calling another script with the definitions:

@echo off

@REM Add variables to be sourced here such as
@REM set PATH="/path/to/some/dir";%PATH%
@REM ... or call another shared script doing so.
@REM call %~dp0\env

MyCode.exe

Because a batch script will keep a console window open, create a VB file with the following

Set oShell = CreateObject ("Wscript.Shell")
Dim strArgs
strArgs = "cmd /c MyCode.bat"
oShell.Run strArgs, 0, false

In the example we assume the program is called MyCode.exe and the batch script has been named in an analogous way MyCode.bat.