Merge pull request #724 from ottok/man-page

.github/workflows/cmake-freebsd.yml

@@ -33,8 +33,7 @@ jobs:
         with:
           release: '14.0'
           usesh: true
-          prepare: pkg install -y cmake ninja
+          prepare: pkg install -y cmake ninja lowdown
           run: |
             CXX=clang++ cmake -B build -G Ninja -DBTOP_STATIC=ON
             cmake --build build --verbose
-

.github/workflows/cmake-linux.yml

@@ -30,11 +30,10 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install build tools
-        run: apk add --no-cache --update clang cmake lld ninja
+        run: apk add --no-cache --update clang cmake lld ninja lowdown
 
       - name: Configure
         run: CXX=clang++ LDFLAGS=-fuse-ld=lld cmake -B build -G Ninja -DBTOP_STATIC=ON
 
       - name: Compile
         run: cmake --build build --verbose
-

.github/workflows/cmake-macos.yml

@@ -32,7 +32,7 @@ jobs:
         run: |
           export HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1
           brew update --quiet
-          brew install --force --overwrite cmake llvm@17 ninja
+          brew install --force --overwrite cmake llvm@17 ninja lowdown
 
       - name: Configure
         run: |
@@ -44,4 +44,3 @@ jobs:
 
       - name: Compile
         run: cmake --build build --verbose
-

.github/workflows/continuous-build-freebsd.yml

@@ -45,7 +45,7 @@ jobs:
           release: '14.0'
           usesh: true
           prepare: |
-            pkg install -y gmake gcc coreutils git
+            pkg install -y gmake gcc coreutils git lowdown
             git config --global --add safe.directory /home/runner/work/btop/btop
           run: |
             CXX=${{ matrix.compiler }} gmake STATIC=true STRIP=true
@@ -59,4 +59,3 @@ jobs:
           name: btop-x86_64-freebsd-14
           path: 'bin/*'
           if-no-files-found: error
-

.github/workflows/continuous-build-openbsd.yml

@@ -42,7 +42,7 @@ jobs:
           release: '7.4'
           usesh: true
           prepare: |
-            pkg_add gmake gcc%11 g++%11 coreutils git
+            pkg_add gmake gcc%11 g++%11 coreutils git lowdown
             git config --global --add safe.directory /home/runner/work/btop/btop
           run: |
             gmake CXX=eg++ STATIC=true STRIP=true
@@ -55,4 +55,3 @@ jobs:
           name: btop-x86_64-openbsd-7.4
           path: 'bin/*'
           if-no-files-found: error
-

.gitignore

@@ -46,6 +46,9 @@ stage/
 *.out
 *.app
 
+# Compiled man page
+btop.1
+
 build
 bin
 btop

CMakeLists.txt

@@ -210,9 +210,24 @@ elseif(CMAKE_SYSTEM_NAME STREQUAL "OpenBSD")
   target_link_libraries(btop kvm::kvm)
 endif()
 
+
+# Check if lowdown is installed
+find_program(LOWDOWN_EXECUTABLE lowdown)
+
+if(LOWDOWN_EXECUTABLE)
+  # Custom target to compile Markdown to man page using lowdown
+  add_custom_target(btop.1 ALL
+      COMMAND lowdown -s -Tman -o btop.1 manpage.md
+      WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  )
+  # Install the man page
+  install(FILES btop.1 DESTINATION "share/man/man1")
+else()
+  message(WARNING "Command 'lowdown' not found: skipping generating man page btop.1")
+endif()
+
 install(TARGETS btop RUNTIME)
 install(FILES "btop.desktop" DESTINATION "share/applications")
 install(FILES "Img/icon.png" DESTINATION "share/icons/hicolor/48x48/apps" RENAME "btop.png")
 install(FILES "Img/icon.svg" DESTINATION "share/icons/hicolor/scalable/apps" RENAME "btop.svg")
 install(DIRECTORY "themes" DESTINATION "share/btop")
-

Makefile

@@ -228,7 +228,7 @@ endif
 
 #? Default Make
 .ONESHELL:
-all: | info rocm_smi info-quiet directories config.h btop
+all: | info rocm_smi info-quiet directories btop.1 config.h btop
 
 ifneq ($(QUIET),true)
 info:
@@ -249,7 +249,6 @@ info:
 	 @true
 endif
 
-
 info-quiet: | info rocm_smi
 	@printf "\n\033[1;92mBuilding btop++ \033[91m(\033[97mv$(BTOP_VERSION)\033[91m) \033[93m$(PLATFORM) \033[96m$(ARCH)\033[0m\n"
 
@@ -280,6 +279,15 @@ $(BUILDDIR)/config.h: $(SRCDIR)/config.h.in | directories
 	@$(VERBOSE) || printf 'sed -e "s|@GIT_COMMIT@|$(GIT_COMMIT)|" -e "s|@CONFIGURE_COMMAND@|$(CONFIGURE_COMMAND)|" -e "s|@COMPILER@|$(CXX)|" -e "s|@COMPILER_VERSION@|$(CXX_VERSION)|" $< | tee $@ > /dev/null\n'
 	@sed -e "s|@GIT_COMMIT@|$(GIT_COMMIT)|" -e "s|@CONFIGURE_COMMAND@|$(CONFIGURE_COMMAND)|" -e "s|@COMPILER@|$(CXX)|" -e "s|@COMPILER_VERSION@|$(CXX_VERSION)|" $< | tee $@ > /dev/null
 
+#? Man page
+btop.1: manpage.md | directories
+ifeq ($(shell command -v lowdown >/dev/null; echo $$?),0)
+	@printf "\n\033[1;92mGenerating man page $@\033[37m...\033[0m\n"
+	lowdown -s -Tman -o $@ $<
+else
+	@printf "\n\033[1;93mCommand 'lowdown' not found: skipping generating man page $@\033[0m\n"
+endif
+
 #? Clean only Objects
 clean:
 	@printf "\033[1;91mRemoving: \033[1;97mbuilt objects...\033[0m\n"
@@ -311,7 +319,11 @@ install:
 	@printf "\033[1;92mInstalling SVG icon to: \033[1;97m$(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps/btop.svg\n"
 	@mkdir -p $(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps
 	@cp -p Img/icon.svg $(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps/btop.svg
-
+ifneq ($(wildcard btop.1),)
+	@printf "\033[1;92mInstalling man page to: \033[1;97m$(DESTDIR)$(PREFIX)/share/man/man1/btop.1\n"
+	@mkdir -p $(DESTDIR)$(PREFIX)/share/man/man1
+	@cp -p btop.1 $(DESTDIR)$(PREFIX)/share/man/man1/btop.1
+endif
 
 #? Set SUID bit for btop as $SU_USER in $SU_GROUP
 setuid:
@@ -321,17 +333,20 @@ setuid:
 	@printf "\033[1;92mSetting SUID bit\033[0m\n"
 	@chmod u+s $(DESTDIR)$(PREFIX)/bin/btop
 
+# With 'rm -v' user will see what files (if any) got removed
 uninstall:
 	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/bin/btop\033[0m\n"
-	@rm -rf $(DESTDIR)$(PREFIX)/bin/btop
+	@rm -rfv $(DESTDIR)$(PREFIX)/bin/btop
 	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/share/btop\033[0m\n"
-	@rm -rf $(DESTDIR)$(PREFIX)/share/btop
+	@rm -rfv $(DESTDIR)$(PREFIX)/share/btop
 	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/share/applications/btop.desktop\033[0m\n"
-	@rm -rf $(DESTDIR)$(PREFIX)/share/applications/btop.desktop
+	@rm -rfv $(DESTDIR)$(PREFIX)/share/applications/btop.desktop
 	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/share/icons/hicolor/48x48/apps/btop.png\033[0m\n"
-	@rm -rf $(DESTDIR)$(PREFIX)/share/icons/hicolor/48x48/apps/btop.png
+	@rm -rfv $(DESTDIR)$(PREFIX)/share/icons/hicolor/48x48/apps/btop.png
 	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps/btop.svg\033[0m\n"
-	@rm -rf $(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps/btop.svg
+	@rm -rfv $(DESTDIR)$(PREFIX)/share/icons/hicolor/scalable/apps/btop.svg
+	@printf "\033[1;91mRemoving: \033[1;97m$(DESTDIR)$(PREFIX)/share/man/man1/btop.1\033[0m\n"
+	@rm -rfv $(DESTDIR)$(PREFIX)/share/man/man1/btop.1
 
 #? Pull in dependency info for *existing* .o files
 -include $(OBJECTS:.$(OBJEXT)=.$(DEPEXT))

README.md

@@ -106,7 +106,7 @@ If you want to help out, test for bugs/fix bugs or just try out the branches:
 **macOS / OSX**
 ```bash
 # Install and use Homebrew or MacPorts package managers for easy dependency installation
-brew install coreutils make gcc@11
+brew install coreutils make gcc@11 lowdown
 git clone https://github.com/aristocratos/btop.git
 cd btop
 git checkout OSX
@@ -115,7 +115,7 @@ gmake
 
 **FreeBSD**
 ```bash
-sudo pkg install gmake gcc11 coreutils git
+sudo pkg install gmake gcc11 coreutils git lowdown
 git clone https://github.com/aristocratos/btop.git
 cd btop
 git checkout freebsd
@@ -395,7 +395,7 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 1. **Install dependencies (example for Ubuntu 21.04 Hirsute)**
 
    ```bash
-   sudo apt install coreutils sed git build-essential gcc-11 g++-11
+   sudo apt install coreutils sed git build-essential gcc-11 g++-11 lowdown
    ```
 
 2. **Clone repository**
@@ -486,12 +486,12 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 
 1. **Install build dependencies**
 
-   Requires Clang / GCC, CMake, Ninja and Git
+   Requires Clang / GCC, CMake, Ninja, Lowdown and Git
 
    For example, with Debian Bookworm:
 
    ```bash
-   sudo apt install cmake git g++ ninja-build
+   sudo apt install cmake git g++ ninja-build lowdown
    ```
 
 2. **Clone the repository**
@@ -569,7 +569,7 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 1. **Install dependencies (example for Homebrew)**
 
    ```bash
-   brew install coreutils make gcc@12
+   brew install coreutils make gcc@12 lowdown
    ```
 
 2. **Clone repository**
@@ -655,11 +655,11 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 
 1. **Install build dependencies**
 
-   Requires Clang, CMake, Ninja and Git
+   Requires Clang, CMake, Ninja, Lowdown and Git
 
    ```bash
    brew update --quiet
-   brew install cmake git llvm ninja
+   brew install cmake git llvm ninja lowdown
    ```
 
 2. **Clone the repository**
@@ -736,7 +736,7 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 1. **Install dependencies**
 
    ```bash
-   sudo pkg install gmake gcc11 coreutils git
+   sudo pkg install gmake gcc11 coreutils git lowdown
    ```
 
 2. **Clone repository**
@@ -823,18 +823,18 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 
 1. **Install build dependencies**
 
-   Requires Clang / GCC, CMake, Ninja and Git
+   Requires Clang / GCC, CMake, Ninja, Lowdown and Git
 
    _**Note:** LLVM's libc++ shipped with FreeBSD 13 is too old and cannot compile btop._
 
 	FreeBSD 14 and later:
    ```bash
-   pkg install cmake ninja
+   pkg install cmake ninja lowdown
    ```
 
 	FreeBSD 13:
    ```bash
-   pkg install cmake gcc13 ninja
+   pkg install cmake gcc13 ninja lowdown
    ```
 
 2. **Clone the repository**
@@ -917,7 +917,7 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 1. **Install dependencies**
 
    ```bash
-   pkg_add gmake gcc%11 g++%11 coreutils git
+   pkg_add gmake gcc%11 g++%11 coreutils git lowdown
    ```
 
 2. **Clone repository**
@@ -1004,12 +1004,12 @@ If you have an AMD GPU `rocm_smi_lib` is required, which may or may not be packa
 
 1. **Install build dependencies**
 
-   Requires GCC, CMake, Ninja and Git
+   Requires GCC, CMake, Ninja, Lowdown and Git
 
    _**Note:** LLVM's libc++ shipped with OpenBSD 7.4 is too old and cannot compile btop._
 
    ```bash
-   pkg_add cmake g++%11 git ninja
+   pkg_add cmake g++%11 git ninja lowdown
    ```
 
 2. **Clone the repository**

manpage.md

@@ -0,0 +1,57 @@
+% btop(1) | User Commands
+%
+% "January  4 2024"
+
+# NAME
+
+btop - Resource monitor that shows usage and stats for processor, memory, disks, network, and processes.
+
+# SYNOPSIS
+
+**btop** [**-lc**] [**-t** | **+t**] [**-p** _id_] [**\-\-utf-force**]
+         [**\-\-debug**] [{**-h** | **\-\-help**} | {**-v** | **\-\-version**}]
+
+# DESCRIPTION
+
+**btop** is a program that shows usage and stats for processor, memory, disks, network, and processes.
+
+# OPTIONS
+
+The program follows the usual GNU command line syntax, with long options
+starting with two dashes ('-'). A summary of options is included below.
+
+**-lc**, **\-\-low-color**
+:   Disable truecolor, converts 24-bit colors to 256-color.
+
+**-t**, **\-\-tty_on**
+:   Force (ON) tty mode, max 16 colors and tty-friendly graph symbols.
+
+**+t**, **\-\-tty_off**
+:   Force (OFF) tty mode.
+
+**-p**, **\-\-preset _id_**
+:   Start with preset, integer value between 0-9.
+
+**\-\-utf-force**
+:   Force start even if no UTF-8 locale was detected.
+
+**\-\-debug**
+:   Start in DEBUG mode: shows microsecond timer for information collect and screen draw functions and sets loglevel to DEBUG.
+
+**-h**, **\-\-help**
+:   Show summary of options.
+
+**-v**, **\-\-version**
+:   Show version of program.
+
+# BUGS
+
+The upstream bug tracker can be found at https://github.com/aristocratos/btop/issues.
+
+# SEE ALSO
+
+**top**(1), **htop**(1)
+
+# AUTHOR
+
+**btop** was written by Jakob P. Liljenberg a.k.a. "Aristocratos".

snap/snapcraft.yaml

@@ -49,14 +49,16 @@ parts:
       - PREFIX=/usr/local
       - STATIC=true
       - ADDFLAGS="-D SNAPPED"
+    # Add 'lowdown' to build dependencies as soon at Snap builder updates from
+    # Ubuntu 20.04 "Focal" to something newer that has Lowdown included
     build-packages:
       - coreutils
       - sed
       - git
       - build-essential
       - gcc-11
       - g++-11
-      
+
     override-pull: |
       snapcraftctl pull
       snapcraftctl set-version "$(git describe --tags | sed 's/^v//' | cut -d "-" -f1)"