ISC licensed by Dino Morelli
Maintained by Dino Morelli
This version can be pinned in stack with:hsinstall-2.2@sha256:7fc7d1bf955cd49acc4f2da461d198fa46386b043eff908e1f3814b80b7639d4,2008

Module documentation for 2.2

hsinstall

Synopsis

Install Haskell software

Description

OVERVIEW

hsinstall is a tool for deploying software projects into directory structures suitable for installation on a system. At this time this means Haskell software but possible future expansion could support other types of projects. It builds upon the stack install command and adds more features. Those are:

  • Copying the LICENSE file into the deployment directory
  • Copying the resources directory into the deployment directory so these files can be located using relative paths at runtime (more on this later in RESOURCES)
  • Building an AppDir directory structure for a project and producing an AppImage

It will be necessary to have the Haskell stack tool on your PATH:
https://docs.haskellstack.org/en/stable/README/

If the AppImage features are desired, you must have these tools on your PATH:
linuxdeploy: https://github.com/linuxdeploy/linuxdeploy/releases
linuxdeploy-plugin-appimage: https://github.com/linuxdeploy/linuxdeploy-plugin-appimage/releases

MODES

hsinstall operates in two modes. The first is a plain deployment with no AppImage creation. The PREFIX will default to AppDir/usr and all binaries in the project will be deployed to AppDir/usr/bin.

The second mode is intended to set up for AppImage creation and is triggered by specifying exactly one EXECUTABLE from the project in the arguments. This will change the PREFIX to AppDir_EXECUTABLE/usr. And only that single executable will be copied to the AppDir_EXECUTABLE/usr/bin directory.

Regardless of which mode is being used, the directory layout will be a standard FHS shape, common in UNIX-like operating systems. Like this:

<PREFIX>/
  bin/...
  share/
    <PROJECT>-<VERSION>/  <-- this is the share directory
      doc/LICENSE
      resources/...

Be aware that when the --delete switch is used the binaries in <PREFIX>/bin WILL NOT be deleted, only the share directory: <PREFIX>/share/<PROJECT>-<VERSION>

APPIMAGE CREATION

Even for a first-time AppImaging, this tool should produce a working AppImage. If missing, it will create default .desktop and .svg files in util/resources/appimage. Customize or replace these to fit your project, and then check these two files into source control for future builds.

The default .desktop file Categories will be populated with ‘Utility;’. We recommend adjusting this using the XDG list of registered categories: https://specifications.freedesktop.org/menu-spec/latest/apa.html

If your application is a command-line program, append this line to the end of the default .desktop file: ‘Terminal=true’

If your application isn’t a command-line tool, we recommend using a proper icon instead of the hsinstall default, which is a command shell icon.

RESOURCES

If present, hsinstall will deploy a resources directory to <PREFIX>/share/PROJECT-VERSION/resources. In order to locate these files at runtime, the hsinstall project includes a library to construct paths relative to the executable. See this source code for help with integrating this into your app: https://github.com/dino-/hsinstall/blob/master/src/lib/HSInstall/Resources.hs

Development

Browse the source

Get source with git and build

$ git clone https://github.com/dino-/hsinstall.git
$ cd hsinstall
$ stack build

If you have the abovementioned linuxdeploy-* programs on your path, we can do something really cool. Use this freshly-built hsinstall to package itself into an AppImage:

$ stack exec hsinstall -- --mk-appimage hsinstall

And you should see an hsinstall-x86_64.AppImage binary in .

Contact

Authors

Dino Morelli [email protected]

Changes

2.2 (2018-11-07)

  • Added actual exception handling
  • Reworded usage and README text

2.1 (2018-10-22)

  • Switched to a a lighter-weight here-document library
  • Updated API documentation

2.0 (2018-10-22)

  • Redesigned as a binary utility to be installed on a system, not a script
  • Added AppImage creation feature
  • Got rid of “bundle” style deployment, it’s all FHS now with a prefix
  • Removed old sample usage app
  • Moved stackage resolver up to lts-12.13
  • Moved copyright date up to 2018

1.6 (2017-07-01)

  • Changed base lower bound from 4.9 to 4.8
  • Updated stack snapshot to lts-8.21
  • Added HCAR listing content
  • Removed defunct cabal stability field
  • Adjusted some documentation in the README
  • Moved copyright date up to 2017

1.5 (2016-10-16)

  • Now creating bin directory prior to stack install
  • Removed comments from auto-generated stack.yaml

1.4 (2016-10-11)

  • Added missing files to extra-source-files
  • Added switch for making a symlink to the app directory

1.3 (2016-10-07)

  • Fixed error in docs

1.2 (2016-10-07)

  • Added example additional script copying code
  • Updated developer instructions
  • Added a tested-with line to the cabal file

1.1 (2016-10-03)

  • Updated to stackage lts-7.2

1.0 (2016-10-03)

  • Cleaned up cabal file
  • Wrote API docs
  • Cleaned up README
  • Aborting the installation if stack install fails
  • Added instructions for compiling install.hs
  • Added library for locating resources at runtime
  • Initial release