# 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](https://appimage.org/) 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](https://github.com/dino-/hsinstall/blob/master/src/lib/HSInstall/Resources.hs)
for help with integrating this into your app.
## Development
Browse [the source](https://github.com/dino-/hsinstall)
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>