diff --git a/CHANGELOG.md b/CHANGELOG.md
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,13 @@
+3.1 (2026-09-05)
+
+ * Redesigned how runtime resources are handled, fixing resource access during
+ development
+ * Rolled back use of VERY modern Cabal API changes, was breaking the reusable
+ library
+ * Removed doc files for the discontinued HCAR
+ * Fixed some errors/omissions in the usage documentation
+
+
3.0 (2026-08-28)
* Extensive operational changes including naming of hsinstall-specific
diff --git a/doc/hcar/hsinstall.tex b/doc/hcar/hsinstall.tex
deleted file mode 100644
--- a/doc/hcar/hsinstall.tex
+++ /dev/null
@@ -1,86 +0,0 @@
-% hsinstall.tex
-\begin{hcarentry}[new]{hsinstall}
-\report{Dino Morelli}
-\status{stable, actively developed}
-\makeheader
-
-\vspace{5mm}
-
-This is a utility to install Haskell programs on a system using
-stack. Although stack does have an `install` command, it only copies
-binaries. Sometimes more is needed, other files and some directory
-structure. hsinstall tries to install the binaries, the LICENSE
-file and also the resources directory if it finds one.
-
-\vspace{5mm}
-
-Installations can be performed in one of two directory
-structures. FHS, or the Filesystem Hierarchy Standard (most UNIX-like
-systems) and what I call "bundle" which is a portable directory
-for the app and all of its files. They look like this:
-
-\vspace{5mm}
-
-bundle is sort-of a self-contained structure like this:
-
-\vspace{5mm}
-
-\begin{verbatim}
- $PREFIX/
- $PROJECT-$VERSION/
- bin/...
- doc/LICENSE
- resources/...
-\end{verbatim}
-
-\vspace{5mm}
-
-fhs is the more traditional UNIX structure like this:
-
-\vspace{5mm}
-
-\begin{verbatim}
- $PREFIX/
- bin/...
- share/
- $PROJECT-$VERSION/
- doc/LICENSE
- resources/...
-\end{verbatim}
-
-\vspace{5mm}
-
-There are two parts to hsinstall that are intended to work
-together. The first part is a Haskell shell script,
-`util/install.hs`. Take a copy of this script and check it into
-a project you're working on. This will be your installation
-script. Running the script with the `--help` switch will explain
-the options. Near the top of the script are default values for
-these options that should be tuned to what your project needs.
-
-\vspace{5mm}
-
-The other part of hsinstall is a library. The install script will try
-to install a `resources` directory if it finds one. the HSInstall
-library can then be used in your code to locate the resources
-at runtime.
-
-\vspace{5mm}
-
-Note that you only need the library if your software has data files
-it needs to locate at runtime in the installation directories. Many
-programs don't have this requirement and can ignore the library
-altogether.
-
-\vspace{5mm}
-
-Source code is available on darcshub, Hackage and Stackage
-
-\FurtherReading
-\begin{compactitem}
- \item hsinstall on darcshub \url{http://hub.darcs.net/dino/hsinstall}
- \item hsinstall on Hackage \url{https://hackage.haskell.org/package/hsinstall}
- \item hsinstall on Stackage \url{https://www.stackage.org/package/hsinstall}
-\end{compactitem}
-
-\end{hcarentry}
diff --git a/hsi-tmpl.hsinstall/share/hsinstall/resources/unix-terminal.svg b/hsi-tmpl.hsinstall/share/hsinstall/resources/unix-terminal.svg
deleted file mode 100644
--- a/hsi-tmpl.hsinstall/share/hsinstall/resources/unix-terminal.svg
+++ /dev/null
@@ -1,320 +0,0 @@
-
-
-
-
diff --git a/hsi-tmpl/share/hsinstall/resources/unix-terminal.svg b/hsi-tmpl/share/hsinstall/resources/unix-terminal.svg
deleted file mode 100644
--- a/hsi-tmpl/share/hsinstall/resources/unix-terminal.svg
+++ /dev/null
@@ -1,320 +0,0 @@
-
-
-
-
diff --git a/hsinstall.cabal b/hsinstall.cabal
--- a/hsinstall.cabal
+++ b/hsinstall.cabal
@@ -1,7 +1,7 @@
cabal-version: 2.2
name: hsinstall
-version: 3.0
+version: 3.1
synopsis: Install Haskell software
description: This is a tool for deploying software projects into directory
structures suitable for installation on a system. It builds upon the `stack
@@ -17,14 +17,12 @@
license-file: LICENSE
build-type: Simple
extra-source-files:
- doc/hcar/hsinstall.tex
doc/MadeByAHuman_01.png
.gitignore
- hsi-tmpl/share/hsinstall/resources/unix-terminal.svg
hsi-tmpl.hsinstall/share/applications/hsinstall.desktop
- hsi-tmpl.hsinstall/share/hsinstall/resources/unix-terminal.svg
hsi-tmpl.hsinstall/share/icons/hicolor/scalable/apps/hsinstall.svg
README.md
+ resources/unix-terminal.svg
stack.yaml
stack.yaml.lock
extra-doc-files:
@@ -103,7 +101,7 @@
hs-source-dirs:
src/app
build-depends:
- Cabal >=3.14.0.0 && <4
+ Cabal >=3.10.3 && <4
, exceptions >=0.10.7 && <1
, formatting >=7.2.0 && <8
, heredoc >=0.2.0.0 && <0.3
diff --git a/resources/unix-terminal.svg b/resources/unix-terminal.svg
new file mode 100644
--- /dev/null
+++ b/resources/unix-terminal.svg
@@ -0,0 +1,320 @@
+
+
+
+
diff --git a/src/app/HSInstall/DeploymentInfo.hs b/src/app/HSInstall/DeploymentInfo.hs
--- a/src/app/HSInstall/DeploymentInfo.hs
+++ b/src/app/HSInstall/DeploymentInfo.hs
@@ -3,8 +3,8 @@
module HSInstall.DeploymentInfo
( BinDir (..)
, DeploymentInfo (..)
- , DocDir (..)
, PrefixDir (..)
+ , ShareDir (..)
, TmplDir (..)
, constructDeploymentInfo
@@ -29,7 +29,6 @@
import Distribution.Simple.PackageDescription (readGenericPackageDescription)
import Distribution.Types.PackageName (unPackageName)
import Distribution.Types.Version (Version)
-import Distribution.Utils.Path (makeSymbolicPath)
import Distribution.Verbosity (normal)
import System.Directory (getDirectoryContents)
import System.FilePath ((), (<.>))
@@ -46,12 +45,12 @@
newtype BinDir = BinDir { v :: FilePath }
-newtype DocDir = DocDir { v :: FilePath }
+newtype ShareDir = ShareDir { v :: FilePath }
data DeploymentInfo = DeploymentInfo
{ prefixDir :: PrefixDir
, binDir :: BinDir
- , docDir :: DocDir
+ , shareDir :: ShareDir
, version :: Version
, tmplDir :: TmplDir
, packageName :: PackageName
@@ -59,13 +58,9 @@
-- This tool is designed to only be run in the top-level directory of a Haskell
--- package that's being packaged for deployment.
-cwd :: FilePath
-cwd = "."
-
-
+-- package that's being packaged for deployment, so we expect "." to be our cwd
locateCabalFile :: IO (Maybe FilePath)
-locateCabalFile = find (isSuffixOf ".cabal") <$> getDirectoryContents cwd
+locateCabalFile = find (isSuffixOf ".cabal") <$> getDirectoryContents "."
constructDeploymentInfo :: BuildTool -> BuildMode -> IO DeploymentInfo
@@ -73,17 +68,15 @@
mbCabalFile <- runMaybeT
$ MaybeT locateCabalFile
<|> MaybeT (makeCabal buildTool >> locateCabalFile)
- let path = Just $ makeSymbolicPath cwd
maybe (throwM NoCabalFiles)
(fmap (constructDeploymentInfo' buildMode . package . packageDescription)
- . readGenericPackageDescription normal path . makeSymbolicPath) mbCabalFile
+ . readGenericPackageDescription normal) mbCabalFile
constructDeploymentInfo' :: BuildMode -> PackageId -> DeploymentInfo
constructDeploymentInfo' buildMode pkgId =
- DeploymentInfo prefixDir' (BinDir binFp)
- (DocDir $ shareFp "doc") (pkgVersion pkgId)
- (mkTmplDirPath buildMode) (PackageName project)
+ DeploymentInfo prefixDir' (BinDir binFp) (ShareDir shareFp)
+ (pkgVersion pkgId) (mkTmplDirPath buildMode) (PackageName project)
where
prefixDir'@(PrefixDir prefixFp) = computePrefixDir buildMode
diff --git a/src/app/HSInstall/Opts.hs b/src/app/HSInstall/Opts.hs
--- a/src/app/HSInstall/Opts.hs
+++ b/src/app/HSInstall/Opts.hs
@@ -161,7 +161,8 @@
hsinstall is a tool for installing a Haskell software project into a directory structure for deployment. It builds upon the `stack install` and `cabal install` commands and adds these features:
- Copies the `LICENSE` file into /share//doc
-- Copies the contents of a template directory stucture in your project (named `hsi-tmpl` or `hsi-tmpl.EXE`) into the destination prefix directory. This can contain additional binaries or scripts, resources, documentation, etc. (more on how this works below)
+- Copies the contents of a template directory stucture in your project (named `hsi-tmpl` or `hsi-tmpl.EXE`) into the destination prefix directory. This can contain additional binaries or scripts, documentation, etc. More on how this works below.
+- Copies the contents of a resources directory stucture in your project (named `resources`) containing data files needed at runtime into the destination share directory. More on how this works below.
- Optionally builds an AppDir-shaped directory structure for the project and produces an AppImage binary
To use hsinstall, it will be necessary to be in the top-level directory of a Haskell project that builds with either cabal or stack. You'll need to have one or the other of the cabal or stack tools on your path as well. Basically, if you can't build the project, hsinstall can't build it either.
@@ -179,29 +180,45 @@
dist (-D|--dist) Pack distributable project binaries and additional files below a PREFIX directory
AppImage (-A|--appimage) Make an AppImage executable of a program and its additional files
+RESOURCES, DATA FILES NEEDED AT RUNTIME
+
+If your project has data files needed at runtime, place them in a `resources` directory in the project root dir. With the helper library below, this works whether it's being run during development, after DIST deployment or as an AppImage.
+
+In order to locate data files at runtime 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: https://codeberg.org/dinofp/hsinstall/src/branch/main/src/lib/HSInstall/Paths.hs
+
+When using it, your code will look something like:
+
+ import HSInstall.Paths (getShareDir)
+ import Paths_PROJECTNAME (getDataDir)
+ import System.FilePath (())
+
+ shareDir <- getShareDir getDataDir
+ let resourcesDir = shareDir "resources"
+
DIST DEPLOYMENT
Running `hsinstall -D` on a project will produce this in . :
hsi-dist/
usr/
- bin/ <-- All binaries in the project
+ bin/ <-- Project binaries
share/
/
doc/
LICENSE
+ resources/ <-- If your project has a `resources` directory, will be copied here
The -p,--prefix switch allows you to set a prefix other than `hsi-dist/usr`. This could be anywhere, like `myproject-2.3` or `/usr/local` or `/opt`
-In addition, if an `hsi-tmpl` directory exists, its contents will be copied into the prefix before build and install. See TEMPLATE DIRECTORY below for more info on this.
+In addition, if an `hsi-tmpl` directory exists, its contents will be copied into the prefix before build and install.
If present, dist mode will copy the contents of the `hsi-tmpl` template directory into ``. Here's an explanation of the `hsi-tmpl` directory contents:
hsi-tmpl/
bin/ <-- Put additional binaries and scripts to be deployed here
- share/
- / <-- Only needed if you have resources
- resources/ <-- Put data files your software will need at runtime here
+ share/ <-- Only needed if you have additional documentation files
+ /
+ doc/ <-- Additional documentation files if desired
APPIMAGE CREATION
@@ -212,12 +229,11 @@
Here's an explanation of the `hsi-tmpl.EXE` directory:
hsi-tmpl.EXE/
- bin/ <-- Put additional binaries and scripts to be deployed here
share/
applications/ <-- Auto-generated for AppImage
.desktop <-- Will be generated by first-time AppImage creation attempt
- / <-- Only needed if you have resources
- resources/ <-- Put data files your software will need at runtime here
+ / <-- Create this if you have additional documentation files
+ doc/ <-- Additional documentation files
icons/ <-- Auto-generated for AppImage
hicolor/
scalable/
@@ -243,9 +259,5 @@
What's happening is gpg can't figure out a way to ask for the gpg key passphrase. Try setting the env like this
$ GPG_TTY=$(tty) hsinstall ...
-
-USING DATA FILES AT RUNTIME
-
-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: https://codeberg.org/dinofp/hsinstall/src/branch/main/src/lib/HSInstall/Paths.hs
Version|] %+ s %+ " Dino Morelli "
diff --git a/src/app/hsinstall.hs b/src/app/hsinstall.hs
--- a/src/app/hsinstall.hs
+++ b/src/app/hsinstall.hs
@@ -15,9 +15,9 @@
installBinaries, warnAboutCabalMultiExe)
import HSInstall.DeploymentInfo
( BinDir (..)
- , DeploymentInfo (binDir, docDir, packageName, prefixDir, tmplDir)
- , DocDir (..)
+ , DeploymentInfo (binDir, packageName, prefixDir, shareDir, tmplDir)
, PrefixDir (..)
+ , ShareDir (..)
, TmplDir (v)
, constructDeploymentInfo
)
@@ -80,7 +80,7 @@
licenseFileExists <- doesFileExist licenseFile
when licenseFileExists $ do
noticeM n $ formatToString ("Copying" %+ string) licenseFile
- let docFp = di.docDir.v
+ let docFp = di.shareDir.v "doc"
createDirectoryIfMissing True docFp
copyFile licenseFile (docFp licenseFile)
@@ -90,3 +90,10 @@
when tmplExists $ do
noticeM n $ formatToString ("Copying distribution files from template dir (" % string % ")") tmplFp
copyTree False tmplFp di.prefixDir.v
+
+ -- Copy resources directory
+ let rsrcFp = "resources"
+ rsrcExists <- doesDirectoryExist rsrcFp
+ when rsrcExists $ do
+ noticeM n "Copying files from resources dir"
+ copyTree False rsrcFp $ di.shareDir.v rsrcFp
diff --git a/src/lib/HSInstall/Paths.hs b/src/lib/HSInstall/Paths.hs
--- a/src/lib/HSInstall/Paths.hs
+++ b/src/lib/HSInstall/Paths.hs
@@ -4,12 +4,13 @@
deployment structure.
-}
module HSInstall.Paths
- ( getShareDir )
+ ( getShareDir
+ )
where
-import System.Directory ( doesDirectoryExist )
-import System.Environment ( getExecutablePath )
-import System.FilePath ( (), takeDirectory, takeFileName )
+import System.Directory (doesDirectoryExist)
+import System.Environment (getExecutablePath)
+import System.FilePath ((), takeDirectory, takeFileName)
{- |
@@ -20,14 +21,19 @@
Usage:
@
- import HSInstall.Paths ( getShareDir )
- import Paths_PROJECTNAME ( getDataDir )
+ import HSInstall.Paths (getShareDir)
+ import Paths_PROJECTNAME (getDataDir)
+ import System.FilePath (())
shareDir <- getShareDir getDataDir
+ let resourcesDir = shareDir "resources"
@
If your binary is at @\/foo\/bar\/usr\/bin\/BINARY@, this library will generate
this path: @\/foo\/bar\/usr\/share\/PROJECTNAME@
+
+ If this directory doesn't exist (because you're developing it and haven't yet
+ constructed the AppImage or haven't built the dist dir), @./@ will be returned.
-}
getShareDir :: IO FilePath -> IO FilePath
getShareDir cabalDataDir = do
@@ -36,9 +42,7 @@
. takeDirectory . takeDirectory <$> getExecutablePath
sharePathExists <- doesDirectoryExist sharePath
- if sharePathExists
- then return sharePath
- else fail $ "Share directory " <> sharePath <> " does not exist"
+ pure $ if sharePathExists then sharePath else "."
stripVersion :: String -> String
diff --git a/stack.yaml b/stack.yaml
--- a/stack.yaml
+++ b/stack.yaml
@@ -4,7 +4,5 @@
- '.'
extra-deps:
-- Cabal-3.14.0.0
-- Cabal-syntax-3.14.0.0
- hslogger-colorfmt-1.0.0
- optparse-applicative-dex-1.0.1
diff --git a/stack.yaml.lock b/stack.yaml.lock
--- a/stack.yaml.lock
+++ b/stack.yaml.lock
@@ -5,20 +5,6 @@
packages:
- completed:
- hackage: Cabal-3.14.0.0@sha256:13d39b2bc652fb4bbd89ccbfabddfa4163dcbe8c6165ec9d18d4f8102fbad320,14137
- pantry-tree:
- sha256: 3d14ae8e5c8f2b56f40594b3f9693cd1ebbcbcb34404f3d402e7ab851b53ea32
- size: 12219
- original:
- hackage: Cabal-3.14.0.0
-- completed:
- hackage: Cabal-syntax-3.14.0.0@sha256:6cd7666c675c29981392d031a9ad402f578234b6195a304c886b84510b0c21cd,7380
- pantry-tree:
- sha256: 2aed3c4195554d93ed1e25c4bacdf8eb7f3e006622bbd17a2e27d4bd0de0cd32
- size: 10977
- original:
- hackage: Cabal-syntax-3.14.0.0
-- completed:
hackage: hslogger-colorfmt-1.0.0@sha256:ec9180c579c73f4aca8c0c9c7fcd4a99f91c9939ab060c78f910d525023a2e40,1312
pantry-tree:
sha256: 851f5cda0546bfc4d3463f70e7420adf0c260266a435e7f6191e659e3e4f65e5