hsinstall
Install Haskell software
https://github.com/dino-/hsinstall#readme
LTS Haskell 22.33: | 2.8 |
Stackage Nightly 2024-09-07: | 2.8 |
Latest on Hackage: | 2.8 |
hsinstall-2.8@sha256:1bfe672ddf29451cd1027c766d079164d1224c5828dd956520b722f8486b431d,2414
Module documentation for 2.8
- HSInstall
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