ISC licensed by Dino Morelli
Maintained by Dino Morelli
This version can be pinned in stack with:hsinstall-2.8@sha256:1bfe672ddf29451cd1027c766d079164d1224c5828dd956520b722f8486b431d,2414

Module documentation for 2.8

hsinstall

Synopsis

Pack a haskell project into a deployable directory structure

Description

OVERVIEW

hsinstall is a tool for installing a Haskell software project into a directory structure for deployment. It builds upon the stack install command and adds these features:

  • Copies the LICENSE file into <PREFIX>/share/<PROJECT-NAME>/doc
  • Copies the contents of a static directory stucture in your project (named hsinstall) into the destination prefix directory. This can contain additional binaries or scripts, resources, documentation, etc. (more on this later in TEMPLATE DIRECTORY)
  • Optionally builds an AppDir directory structure for the project and produces an AppImage binary

To use hsinstall, 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

Running hsinstall on a project for the first time and with no arguments will produce this in . :

AppDir/
  usr/
    bin/  <-- All binaries in the project
    share/
      <PROJECT-NAME>/
        doc/
          LICENSE

The -p,–prefix switch allows you to set a prefix other than AppDir/usr. This could be anywhere, like myproject-2.3 or /usr/local or /opt

In addition, if an hsinstall directory exists, its contents will be copied into the prefix before build and install. See TEMPLATE DIRECTORY below for more info on this.

APPIMAGE CREATION

The -i,–mk-appimage switch will change the default prefix to EXE.AppDir/usr and only the specified EXE will be installed into <PREFIX>/bin, AppImages are intended to be made for exactly one binary.

If .desktop and .svg files are not found in the hsinstall directory, defaults will be created for you and placed in the correct subdirs. Check these 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 a line containing this to the end of the default .desktop file: ‘Terminal=true’

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

For more info on AppImage: https://appimage.org/

TEMPLATE DIRECTORY

If present, hsinstall will copy the contents of the hsinstall template directory into <PREFIX>. Here’s an explanation of the hsinstall directory contents:

hsinstall/
  bin/  <-- Put additional binaries and scripts to be deployed here
  share/
    applications/  <-- Only for AppImage
      <EXE>.desktop  <-- Will be generated by first-time AppImage creation attempt
    <PROJECT-NAME>/  <-- Only needed if you have resources
      resources/  <-- Put data files your software will need at runtime here
    icons/  <-- Only for AppImage
      hicolor/
        scalable/
          apps/
            <EXE>.svg  <-- Will be generated by first-time AppImage creation attempt

In order to locate data files at runtime, including resources, the hsinstall project includes a library to construct the share path relative to the executable. See this source code for help with integrating this into your app.

Development

Browse the source

Get source with git and build

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

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-y.z-x86_64.AppImage binary in .

Tip: Use git clean -df to blow away untracked things like the AppDir and AppImage artifacts.

Contact

Authors

Dino Morelli [email protected]

Changes

2.8 (2023-01-28)

  • Fix for change to the Cabal Distribution API
  • Switched from hpack to modern cabal
  • Moved copyright date up to 2023

2.7 (2021-12-01)

  • Changed how default prefix is constructed
  • Turned off stdout/stderr buffering
  • Support projects that build with either cabal or stack
  • Removed an unused import
  • Now forcing all cabal commands to be v2-
  • Using newtype wrappers for DeploymentInfo fields
  • Using Haskell core type Version for version
  • Removed shareDir and rsrcDir from DeploymentInfo
  • Now using newtype wrappers for all Options fields
  • Added more newtype wrappers around many data types
  • Applied hlint suggestions
  • Moved stack resolver up to lts-18.18

2.6 (2020-01-12)

  • Moved stack resolver up to lts-14.20
  • Switched from fmt library to Text.Printf
  • Try to force hpack cabal file creation if it’s missing
  • Moved copyright date up to 2020
  • Fixed various problems in the README

2.5 (2019-12-01)

  • Using an infoHelper for the –version switch
  • Moved Stackage snapshot up to lts-14.8
  • Updated usage to reflect the new template dir behavior
  • Changed lib/HSInstall/Resources.hs to Paths.hs
  • Added custom code for recursive file copying
  • Fixed bug with default prefix directory
  • Removed the –delete switch
  • Rolled EXE argument into –mk-appimage switch
  • Changed how resources and AppImage source files are handled
  • Added a handy tip about git clean
  • Removed code to force cabal file creation

2.4 (2019-04-26)

  • Moved copyright date up to 2019
  • Separated code into more modules for clarity
  • Switched from GetOpt to optparse-applicative
  • Fixed API doc wording
  • Adjusted code with hlint’s advice
  • Now trying to force stack/hpack to generate the cabal file if it’s missing
  • Added app version number to AppImage filename

2.3 (2019-03-03)

  • Changed deployment dir name to EXECUTABLE.AppDir
  • Switched all uses of Text.Printf to the Fmt library
  • Moved Stackage resolver up to lts-13.9

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