Package NumbatUI to ease installation

.github/workflows/deb.yml

@@ -0,0 +1,76 @@
+name: Build Debian package
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+    tags:
+      - 'v*'
+  pull_request:
+
+jobs:
+  build-deb:
+    runs-on: ubuntu-latest
+    container:
+      image: debian:trixie
+    permissions:
+      contents: write   # needed to attach the .deb to a release on tag builds
+
+    steps:
+      - name: Install base tooling
+        run: |
+          apt-get update
+          DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+            git ca-certificates build-essential devscripts equivs lintian
+
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Install build dependencies from debian/control
+        run: |
+          mk-build-deps --install --remove \
+            --tool 'apt-get -y --no-install-recommends' debian/control
+
+      - name: Build the package
+        run: dpkg-buildpackage -us -uc -b
+
+      - name: Run lintian (informational)
+        run: lintian ../*.deb || true
+
+      - name: Compute artifact slug
+        id: slug
+        run: |
+          # github.ref_name contains a slash on pull_request events (e.g.
+          # "4/merge") and for branches like "feature/x"; upload-artifact
+          # rejects "/" in names. Replace it. Note the default shell here is
+          # POSIX sh, so use tr rather than bash parameter expansion.
+          slug="$(printf '%s' "$GITHUB_REF_NAME" | tr '/' '-')"
+          echo "value=${slug}-${GITHUB_SHA}" >> "$GITHUB_OUTPUT"
+
+      - name: Collect artifacts
+        run: |
+          mkdir -p dist
+          mv ../*.deb dist/
+          ls -l dist/
+
+      - name: Upload .deb artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: numbatui-deb-${{ steps.slug.outputs.value }}
+          path: dist/numbatui_*_amd64.deb
+          if-no-files-found: error
+
+      - name: Upload debug symbols
+        uses: actions/upload-artifact@v6
+        with:
+          name: numbatui-dbgsym-${{ steps.slug.outputs.value }}
+          path: dist/numbatui-dbgsym_*_amd64.deb
+          if-no-files-found: warn
+          retention-days: 7
+
+      - name: Attach .deb to release
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/numbatui_*_amd64.deb

CMakeLists.txt

@@ -843,3 +843,8 @@ elseif(WIN32)
 		endif()
 	endforeach()
 endif ()
+
+
+# Installation rules (FHS layout) for building distribution packages such as
+# Debian .deb. Included last so the application/indexer targets already exist.
+include(cmake/install.cmake)

README.md

@@ -132,6 +132,45 @@ forwarding required, unlike the Docker image documented above.
 Note: This build purposely disables C++, Python language indexation features.
 They shall be re-enabled in future releases.
 
+### Debian package (.deb)
+
+On Debian/Ubuntu, NumbatUI can be installed as a native `.deb` package. This
+installs the GUI and indexer to `/usr/bin`, the runtime data to
+`/usr/share/numbatui`, and registers the desktop entry, MIME association
+(`*.srctrlprj`) and application icons.
+
+#### Install a prebuilt package
+
+Every push to the `main` and `dev` branches builds a `.deb` in CI. Download it
+from the **Actions** tab: open the latest *Build Debian package* run and grab
+the `numbatui-deb-<branch>-<sha>` artifact (tagged `v*` releases also attach the
+`.deb` to the GitHub release). Then:
+
+```bash
+sudo apt install ./numbatui_*_amd64.deb
+```
+
+`apt` pulls in the required Qt 6 and Boost runtime libraries automatically.
+
+#### Build the package yourself
+
+From a checkout of the repository:
+
+```bash
+# one-off: install the build dependencies declared in debian/control
+sudo apt build-dep .
+# or, without a deb-src entry:
+#   sudo apt install devscripts equivs && sudo mk-build-deps -i debian/control
+
+# build the binary package (the .deb is written to the parent directory)
+dpkg-buildpackage -us -uc -b
+ls ../numbatui_*_amd64.deb
+```
+
+The packaging lives in `debian/` and drives the same CMake build as above
+through `debhelper`. See [`debian/README.source`](./debian/README.source) for
+the packaging design and how to bump the package version.
+
 ### Note on Docker on macOS
 
 The Docker image documented in [Usage](#usage) is Linux-only and ships a Qt

cmake/install.cmake

@@ -0,0 +1,112 @@
+# ------------------------------------------------------------------------------
+# install.cmake
+#
+# FHS-compliant installation rules used to build distribution packages
+# (e.g. Debian .deb via dpkg-buildpackage / debhelper).
+#
+# Layout produced (prefix defaults to /usr):
+#   <bindir>/NumbatUI                         the GUI binary
+#   <bindir>/numbatui                         symlink -> NumbatUI
+#   <bindir>/numbatui_indexer                 the indexer binary
+#   <datadir>/numbatui/data/...               runtime data (color schemes, gui, ...)
+#   <datadir>/numbatui/user/...               user template tree (projects, settings)
+#   <datadir>/applications/numbatui.desktop   desktop entry
+#   <datadir>/mime/packages/numbatui.xml      MIME association for *.srctrlprj
+#   <datadir>/icons/hicolor/scalable/...      scalable application icon
+#   <datadir>/icons/hicolor/<size>/...        rasterized icons (if ImageMagick found)
+#
+# This module is only meaningful on Linux; macOS uses the bundle logic and
+# Windows uses the WiX/installer logic elsewhere in the tree.
+# ------------------------------------------------------------------------------
+
+if (NOT (UNIX AND NOT APPLE))
+	return()
+endif()
+
+include(GNUInstallDirs)
+
+# Where NumbatUI's own shared data lives, e.g. /usr/share/numbatui
+set(NUMBATUI_PKGDATADIR "${CMAKE_INSTALL_DATADIR}/numbatui")
+
+# --- Binaries -----------------------------------------------------------------
+# ${APP_PROJECT_NAME}  -> output name "NumbatUI"
+# ${APP_INDEXER_NAME}  -> output name "numbatui_indexer" (set via OUTPUT_NAME)
+install(TARGETS ${APP_PROJECT_NAME} ${APP_INDEXER_NAME}
+	RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
+)
+
+# Lower-case convenience symlink (the .desktop entry launches "numbatui").
+# Created relative so it stays valid regardless of the install prefix / DESTDIR.
+install(CODE "
+	set(_bindir \"\$ENV{DESTDIR}${CMAKE_INSTALL_FULL_BINDIR}\")
+	file(MAKE_DIRECTORY \"\${_bindir}\")
+	execute_process(COMMAND \"${CMAKE_COMMAND}\" -E create_symlink
+		NumbatUI \"\${_bindir}/numbatui\")
+")
+
+# --- Runtime data -------------------------------------------------------------
+# The application resolves resources at <sharedDataDir>/data/... . On an FHS
+# install <sharedDataDir> is <prefix>/share/numbatui (see includesLinux.h).
+install(DIRECTORY "${CMAKE_SOURCE_DIR}/bin/app/data/"
+	DESTINATION "${NUMBATUI_PKGDATADIR}/data"
+	PATTERN "install" EXCLUDE      # Windows-only uninstaller scripts
+)
+
+# User template tree (sample projects + ApplicationSettings template). At first
+# launch the app copies <sharedDataDir>/user/ into ~/.config/numbatui/.
+install(DIRECTORY "${CMAKE_SOURCE_DIR}/bin/app/user/"
+	DESTINATION "${NUMBATUI_PKGDATADIR}/user"
+)
+
+# --- Desktop integration ------------------------------------------------------
+install(FILES "${CMAKE_SOURCE_DIR}/setup/Linux/data/numbatui.desktop"
+	DESTINATION "${CMAKE_INSTALL_DATADIR}/applications"
+)
+
+# shared-mime-info expects the file named after the package.
+install(FILES "${CMAKE_SOURCE_DIR}/setup/Linux/data/numbatui-mime.xml"
+	DESTINATION "${CMAKE_INSTALL_DATADIR}/mime/packages"
+	RENAME numbatui.xml
+)
+
+# --- Icons --------------------------------------------------------------------
+# Always ship the scalable SVG master.
+install(FILES "${CMAKE_SOURCE_DIR}/logo/numbat_ui.svg"
+	DESTINATION "${CMAKE_INSTALL_DATADIR}/icons/hicolor/scalable/apps"
+	RENAME numbatui.svg
+)
+
+# Additionally rasterize standard hicolor sizes when ImageMagick is available so
+# the icon shows up in environments that do not render SVG theme icons. This is
+# wired into the build graph (a dependency of the GUI target) rather than done
+# at install time, so the generated files exist before `cmake --install`.
+find_program(IMAGEMAGICK_CONVERT NAMES magick convert)
+if (IMAGEMAGICK_CONVERT)
+	set(_icon_master "${CMAKE_SOURCE_DIR}/logo/numbatui_1024.png")
+	set(_icon_sizes 16 32 48 64 128 256 512)
+	set(_icon_outputs "")
+	foreach (_sz IN LISTS _icon_sizes)
+		set(_out "${CMAKE_BINARY_DIR}/icons/${_sz}x${_sz}/numbatui.png")
+		add_custom_command(
+			OUTPUT "${_out}"
+			COMMAND "${CMAKE_COMMAND}" -E make_directory "${CMAKE_BINARY_DIR}/icons/${_sz}x${_sz}"
+			COMMAND "${IMAGEMAGICK_CONVERT}" "${_icon_master}"
+			        -resize "${_sz}x${_sz}" "${_out}"
+			DEPENDS "${_icon_master}"
+			COMMENT "Generating ${_sz}x${_sz} application icon"
+			VERBATIM
+		)
+		list(APPEND _icon_outputs "${_out}")
+		install(FILES "${_out}"
+			DESTINATION "${CMAKE_INSTALL_DATADIR}/icons/hicolor/${_sz}x${_sz}/apps"
+		)
+	endforeach()
+	add_custom_target(numbatui_icons ALL DEPENDS ${_icon_outputs})
+	if (TARGET ${APP_PROJECT_NAME})
+		add_dependencies(${APP_PROJECT_NAME} numbatui_icons)
+	endif()
+else()
+	message(STATUS "ImageMagick not found: only the scalable SVG icon will be installed.")
+endif()
+
+message(STATUS "Install rules enabled (prefix: ${CMAKE_INSTALL_PREFIX}, data: ${NUMBATUI_PKGDATADIR})")

cmake/productVersion.h.in

@@ -5,7 +5,7 @@
 #define GIT_VERSION_NUMBER "@GIT_VERSION_NUMBER@"
 #define GIT_COMMIT_HASH "@GIT_COMMIT_HASH@"
 #define GIT_COMMIT_TIME "@GIT_COMMIT_TIME@"
-#define VERSION_YEAR @VERSION_YEAR@
+#define VERSION_MAJOR @VERSION_MAJOR@
 #define VERSION_MINOR @VERSION_MINOR@
 #define VERSION_COMMIT @VERSION_COMMIT@
 

cmake/version.cmake

@@ -2,8 +2,8 @@
 set(GIT_BRANCH "")
 set(GIT_COMMIT_HASH "")
 set(GIT_VERSION_NUMBER "")
-set(VERSION_YEAR "0")
-set(VERSION_MINOR "0")
+set(VERSION_MAJOR "0")
+set(VERSION_MINOR "1")
 set(VERSION_COMMIT "0")
 # set(BUILD_TYPE "")
 # if(EXISTS "${CMAKE_SOURCE_DIR}/.git")
@@ -36,19 +36,19 @@ set(VERSION_COMMIT "0")
 #         OUTPUT_VARIABLE GIT_VERSION_NUMBER
 #         OUTPUT_STRIP_TRAILING_WHITESPACE
 #     )
-#     string(REGEX REPLACE "^([0-9]+)\\..*" "\\1" VERSION_YEAR "${GIT_VERSION_NUMBER}")
+#     string(REGEX REPLACE "^([0-9]+)\\..*" "\\1" VERSION_MAJOR "${GIT_VERSION_NUMBER}")
 #     string(REGEX REPLACE "^[0-9]+\\.([0-9]+).*" "\\1" VERSION_MINOR "${GIT_VERSION_NUMBER}")
 #     string(REGEX REPLACE "^[0-9]+\\.[0-9]+-([0-9]+).*" "\\1" VERSION_COMMIT "${GIT_VERSION_NUMBER}")
 # endif(EXISTS "${CMAKE_SOURCE_DIR}/.git")
 
-set(VERSION_STRING "${VERSION_YEAR}.${VERSION_MINOR}.${VERSION_COMMIT}")
+set(VERSION_STRING "${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_COMMIT}")
 
 message(STATUS "Version: ${VERSION_STRING}")
 
 # message(STATUS "Git current branch: ${GIT_BRANCH}")
 # message(STATUS "Git version number: " ${GIT_VERSION_NUMBER} )
 # message(STATUS "Git commit hash: ${GIT_COMMIT_HASH}")
 # message(STATUS "Git commit time: ${GIT_COMMIT_TIME}")
-# message(STATUS "Version year: ${VERSION_YEAR}")
+# message(STATUS "Version year: ${VERSION_MAJOR}")
 # message(STATUS "Version minor: ${VERSION_MINOR}")
 # message(STATUS "Version commit: ${VERSION_COMMIT}")

debian/NumbatUI.1

@@ -0,0 +1,43 @@
+.TH NUMBATUI 1 "2026-06-04" "NumbatUI" "User Commands"
+.SH NAME
+NumbatUI \- source code and graph explorer
+.SH SYNOPSIS
+.B NumbatUI
+.RI [ PROJECT ]
+.br
+.B NumbatUI
+.B index
+.RI [ options ]
+.I PROJECT
+.SH DESCRIPTION
+.B NumbatUI
+is an interactive source explorer, a Quarkslab fork of Sourcetrail. It lets
+you navigate code and graph-based data through linked graph and code views.
+.PP
+When started without arguments it opens the graphical interface. A project
+file (extension
+.IR .srctrlprj )
+may be passed to open it directly.
+.SH OPTIONS
+.TP
+.BI index " PROJECT"
+Index the given project from the command line without starting the graphical
+interface.
+.TP
+.B \-\-help
+Show the full list of commands and options and exit.
+.TP
+.B \-\-version
+Show version information and exit.
+.SH FILES
+.TP
+.I ~/.config/numbatui/
+Per-user configuration, application settings and sample projects, populated on
+first launch.
+.TP
+.I /usr/share/numbatui/
+Read-only application data (color schemes, fonts, GUI resources).
+.SH SEE ALSO
+.BR numbatui_indexer (1)
+.PP
+Project home page: <https://github.com/quarkslab/NumbatUI>.