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 dino@ui3.info