Installation

The following sections explain how to install the software from source, for each supported platform. An installation program for Windows and an app bundle for Mac OS X are also available, and can be used to install pre-compiled binary versions of the software without the need to follow the instructions below.

Installation on Linux

The package depends on the GNU Linear Programming Kit (GLPK) (versions 4.45 and 4.57 are known to work), BLAS and LAPACK. On Debian/Ubuntu-based systems, the required packages are libglpk-dev, libblas-dev and liblapack-dev. On Fedora/CentOS/RHEL-based systems, the required packages are gplk-devel, blas-devel and lapack-devel.

The git VCS client is required to download the source code. To install from source, a Haskell toolchain including either ghc 8.0.2 and cabal-install 2.0, or including stack 1.6.1, is required. (Later versions should also work.) The following subsections provide instructions for installing the package using either cabal-install or stack. More general instructions for various different systems are available from the Haskell.org downloads page.

Installation from source with cabal-install

ghc 8.0.2 and cabal-install 2.0 or later may be available using your system package manager. Note that some distributions package older versions of ghc and cabal-install by default, so you may need to upgrade.

You can check the versions that are currently installed (if any) by running:

ghc --version
cabal --version

If newer versions are required, the easiest way to upgrade is to find an alternative package source that includes the newer versions. For Ubuntu 16.04 or later, and compatible distributions, a private package archive (PPA) is available. The following commands (run as root or with sudo) will register the PPA and install all the necessary dependencies:

add-apt-repository ppa:hvr/ghc
apt-get update
apt-get install cabal-install-2.0 ghc-8.0.2 libglpk-dev libblas-dev liblapack-dev

You will also need to add /opt/ghc/bin to your PATH, either by running export PATH=/opt/ghc/bin:$PATH or more permanently (e.g. by adding PATH=/opt/ghc/bin:$PATH to your ~/.profile and running source ~/.profile).

For Debian, binary packages are available, and you should follow the instructions on that page. For other distributions, you should refer to the Haskell.org Linux downloads page to see if packages for your distribution are available.

If a pre-packaged version of ghc 8.0.2 is not available for your distribution, you can download binary packages from the GHC website.

If a pre-packaged version of cabal-install 2.0 or later is not available for your distribution, you can download binary packages from the Cabal website, or install an earlier version and upgrade by running:

cabal update
cabal install Cabal cabal-install

Once you have the dependencies installed, the following commands will check out the most recent version of the source code and build it:

git clone git@gitlab.com:well-typed/product-mix-auction.git
cd product-mix-auction
git submodule update --init

cabal update
cabal new-build

This will automatically download and compile Haskell library dependencies, if necessary.

You can then run deploy/install.sh (as root), which will install the built binaries under /opt/pma and install a pma-server.service unit file (assuming your host uses the systemd init system). If you wish to run the server or CLI app directly, add /opt/pma/bin to your PATH.

To download and build a more recent version of the sources, do the following:

git pull
git submodule update
cabal update
cabal new-build

You can then run deploy/install.sh (as root) again to install the updated binaries (you may need to stop the service and restart it after copying across the new files).

Installation from source with stack

stack 1.6.1 or later can be installed following the instructions in its documentation.

Once you have the dependencies installed, the following commands will check out the most recent version of the source code and build it:

git clone git@gitlab.com:well-typed/product-mix-auction.git
cd product-mix-auction
git submodule update --init

stack install

This will automatically download ghc and use it to compile Haskell library dependencies, if necessary. The pma and pma-server binaries will be installed in ~/.local/bin by default, which you may need to add to your PATH.

To download and build a more recent version of the sources, do the following:

git pull
git submodule update
stack install

Building the documentation

The users’ guide is written using the Sphinx documentation generator. If you wish to build the users’ guide, install Sphinx following its installation instructions (for Ubuntu or Debian systems, you can sudo apt-get install python-sphinx).

Run make <format> in the doc/ directory to build the docs in the given format. To see a list of supported formats, run make without any arguments. For example, to build and install the HTML format documentation:

cd doc
make html
cp -r _build/html /opt/pma/doc/html

To build the Haddock documentation, build the Haskell program as described above, then run the following in the product-mix-auction directory if you are using cabal:

cabal new-haddock
mkdir -p /opt/pma/doc
cp -r dist-newstyle/build/x86_64-linux/ghc-8.0.2/product-mix-auction-0.1.0.0/doc/html/product-mix-auction /opt/pma/doc/haddock

Alternatively, if you are using stack:

stack haddock

Installation on Windows

The following instructions assume a 64-bit Windows edition. Building and installing on 32-bit editions should be possible, but will require a few adjustments and is not officially supported.

Moreover, the instructions explicitly specify versions of the dependencies that are known to work. It may be possible to use other versions, but this is untested and is likely to require more effort (especially if using a different version of MSYS).

If you wish to build a Windows installer from a Linux host using a virtual machine, see Configuring a virtual machine below.

Installation from source

  1. Install stack 1.7.1 by downloading and running stack-1.7.1-windows-x86_64-installer.exe from the Stack website.

  2. Download and unpack the Product-Mix Auction source code somewhere suitable (hereafter, the location of this directory will be referred to as product-mix-auction).

    If you wish to build the development version, it is recommended to use Git for Windows Portable (PortableGit-2.18.0-64-bit.7z.exe or a later release from the Git download page). This will avoid potential conflicts between different installations of MSYS from stack and git. Assuming you install this to C:\PortableGit, you can check out the source code by opening cmd.exe and running:

    C:\PortableGit\cmd\git.exe clone git@gitlab.com:well-typed/product-mix-auction.git product-mix-auction
cd product-mix-auction
C:\PortableGit\cmd\git.exe submodule update --init

    Alternatively, you can download a ZIP file of the source code, or if installing in a VM with a Windows guest, you can clone the source code repository on the host and share the folder with the guest.

  3. Download and unpack winglpk-4.63.zip into product-mix-auction\thirdparty\glpk-4.63. This contains pre-built Windows binaries from the WinGLPK project. Alternatively, you can try building from source yourself using the GLPK sources.

  4. Download and unpack OpenBLAS-v0.2.19-Win64-int32.zip into product-mix-auction\thirdparty\OpenBLAS-v0.2.19-Win64-int32. This contains pre-built Windows binaries from the OpenBLAS project. Alternatively, you can try building from source yourself using the OpenBLAS sources.

  5. Run cmd.exe and cd to the product-mix-auction source code directory.

  6. Run stack which will install GHC and a suitable MSYS environment, and download necessary files:

    stack --stack-yaml stack-win64.yaml setup
stack --stack-yaml stack-win64.yaml update

    If you receive an error message saying “certificate has unknown CA”, look for the host name mentioned in the error message, and connect to it over HTTPS using Internet Explorer or Edge. This will typically be https://raw.githubusercontent.com. See the relevant Stack issue for more details.

    The second command may take some time to download the Hackage package index, but try not to interrupt it. If any downloads are interrupted, and re-trying the command fails, you may need to delete the partially downloaded files and start again. These are typically stored in C:\Users\User\AppData\Local\Programs\stack\x86_64-windows (or stack path --programs) and C:\sr\indices (under stack path --stack-root).

  7. Start an MINGW64 shell by running:

    stack --stack-yaml stack-win64.yaml exec bash

    Note that there are multiple shells available with MSYS, and the behaviour of both stack and MSYS has changed over time. Check that echo $MSYSTEM returns MINGW64 and gcc -v says that you are running GCC version 6.2.0 (distributed with GHC 8.2).

  8. In the MINGW64 shell, install the libraries needed for openblas using pacman (bundled with MSYS):

    pacman -S mingw-w64-x86_64-gcc-fortran=7.3.0

    Note that you must use mingw-w64-x86_64-gcc-fortran, not gcc-fortran. Sometimes pacman package downloads are unreliable, so you may need multiple repeated attempts, but it should work out eventually. Do not attempt to upgrade any pacman packages though, especially not pacman itself, because this may brick the MSYS environment.

  9. Copy the following libraries into the product-mix-auction directory (replacing STACK_PROGRAMS_PATH with the path given by stack path --programs, which will typically be C:\Users\User\AppData\Local\Programs\stack\x86_64-windows):

    • thirdparty\glpk-4.63\w64\glpk_4_63.dll
    • thirdparty\OpenBLAS-v0.2.19-Win64-int32\bin\libopenblas.dll
    • STACK_PROGRAMS_PATH\msys2-20180531\mingw64\bin\libgcc_s_seh-1.dll
    • STACK_PROGRAMS_PATH\msys2-20180531\mingw64\bin\libgfortran-4.dll
    • STACK_PROGRAMS_PATH\msys2-20180531\mingw64\bin\libquadmath-0.dll
    • STACK_PROGRAMS_PATH\msys2-20180531\mingw64\bin\libwinpthread-1.dll

    In the product-mix-auction directory, make a copy of glpk_4_63.dll named glpk.dll (so that glpk-hs can find it) and copy libgfortran-4.dll to libgfortran.dll and libgfortran-3.dll (so that hmatrix and openblas can find it).

  10. Exit the MINGW64 shell if necessary and return to the cmd.exe shell in the product-mix-auction directory. Finally, compile the package along with its Haskell dependencies:

    stack --stack-yaml stack-win64.yaml install

    This will install pma.exe and pma-server.exe in the current directory (controlled by the local-bin-path option in stack-win64.yaml). You may wish to add this directory to your PATH. Alternatively, read on to Creating an installer bundle.

Creating an installer bundle

  1. Follow the steps in Installation from source above to build pma.exe and pma-server.exe.
  2. Install Inno Setup by downloading and running innosetup-5.5.9.exe from the Inno Setup website (later versions are also likely to work).
  3. Open deploy/win64/pma-win64.iss with Inno Setup Compiler, and select Build ‣ Compile from the menu.
  4. Inno Setup Compiler should produce a self-contained Windows installer binary in deploy/win64/output/pma-setup.exe. Running this installer will (by default) install the application to C:\Program Files\ProductMixAuction and modify the PATH so that pma and pma-server are available.

Configuring a virtual machine

These instructions are necessary only if you do not have a Windows machine available, and wish to build the Windows installer using a virtual machine on a Linux host.

  1. Download the MS Edge on Win10 image for VirtualBox and unzip it.
  2. Install VirtualBox and its guest additions CD image. On Ubuntu-based systems, the required packages are virtualbox and virtualbox-guest-additions-iso.
  3. Add your user account to the vboxusers group (sudo usermod -a -G vboxusers $(whoami)) and either log out and log in again, or run su - $(whoami) to give a shell with the new group membership available.
  4. Run virtualbox and import the appliance (.ova file) downloaded earlier.
  5. Configure the appliance settings. The ideal settings may depend on your exact system configuration, but the following example may be useful:
    • General: bidirectional shared clipboard
    • System: 8192 MB base memory, 4 processors, 90% execution cap, KVM paravirtualization
    • Storage: add an optical drive
    • Network: adapter 1 attached to Bridged Adapter
    • Shared folders: add a directory in which to build the software
  6. Start the virtual machine. Insert the VirtualBox guest additions CD image (from the Devices menu), install the guest additions, then reboot the virtual machine.
  7. If you are using Git for Windows to download the source code, and need access to non-public repositories, copy your SSH key to C:\Users\IEUser\.ssh.
  8. Inside the virtual machine, follow the instructions from Installation from source above.

Installation on Mac OS X

Installation from source

For installation from source, a working Haskell toolchain is required. The easiest way to achieve this is to install stack. Stack requires Xcode, so install that first, then proceed to the stack installation.

The Product-Mix Auction package depends on GLPK. Download it from here, and follow the installation instructions contained in the package. Thus, something like:

curl -o glpk-4.63.tar.gz http://ftp.gnu.org/gnu/glpk/glpk-4.63.tar.gz
tar xf glpk-4.63.tar.gz
cd glpk-4.63
./configure
make
sudo make install

Once you have the dependencies installed, the following commands will check out the most recent version of the source code and build it:

git clone git@gitlab.com:well-typed/product-mix-auction.git
cd product-mix-auction
git submodule update --init
stack setup # only required the first time; this will also install a Haskell
            # compiler, so expect it to take a while
stack install --extra-lib-dirs=/usr/local/lib --extra-include-dirs=/usr/local/include

This should give you two binaries under ~/.local/bin/: pma, and pma-server.

Creating an installer bundle

This requires an additional dependency: dylibbundler. Installing from source:

git clone https://github.com/auriamg/macdylibbundler/
cd macdylibbundler
make
sudo make install

Creating app bundles: just run the deploy/make-dmg.sh script:

./deploy/make-dmg.sh

This will create DMG images for pma and pma-server in ./dist/osx.

Getting started

Once you have the pma binary installed and available on your PATH, you can proceed to Running auctions via the command-line interface.

Once you have the pma-server binary installed and running, you can proceed to Running auctions via the web app. Note that the server requires the pma binary to be available on the PATH, or for the --pma-binary option to be used to specify its location.