Update v6 to have Debian Packages (capstone-engine#2579)

Author: AndrewQuijano

.github/workflows/build_deb.yml

@@ -15,6 +15,29 @@ jobs:
       with:
         submodules: true
 
+    - name: Make setup.sh and check_capstone.sh are executable
+      run: |
+        chmod +x ./packages/deb/setup.sh
+        chmod +x ./packages/deb/check_capstone.sh
+        
+    - name: Build Debian Package
+      working-directory: ./packages/deb
+      run: ./setup.sh ${{ github.event.release.tag_name }}
+    
+    - name: Run sanity checks on the Debian package
+      working-directory: ./packages/deb
+      run: |
+        ./check_capstone.sh ./libcapstone-dev_${{ github.event.release.tag_name }}_amd64.deb
+      
+    - name: Upload debian package to release
+      uses: softprops/action-gh-release@v2
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        tag_name: ${{ github.event.release.tag_name }}
+        files: |
+          ./packages/deb/*.deb
+  
     - name: Create archive
       id: archive
       run: |

.github/workflows/build_release.yml

@@ -19,9 +19,16 @@ endif()
 # https://cmake.org/cmake/help/latest/policy/CMP0042.html
 cmake_policy(SET CMP0042 NEW)
 
-project(capstone
-    VERSION 6.0
-)
+# Check if VERSION is provided externally, otherwise default to 6.0.0
+if(NOT DEFINED PROJECT_VERSION)
+    set(PROJECT_VERSION "6.0.0")
+endif()
+
+# Extract the major, minor, and patch versions
+string(REGEX MATCH "^[0-9]+\\.[0-9]+\\.[0-9]+" PROJECT_VERSION_BASE ${PROJECT_VERSION})
+
+# Set the project version without the pre-release identifier
+project(capstone VERSION ${PROJECT_VERSION_BASE})
 
 set(UNIX_COMPILER_OPTIONS -Werror -Wall -Warray-bounds -Wshift-negative-value -Wreturn-type -Wformat -Wmissing-braces -Wunused-function -Warray-bounds -Wunused-variable -Wparentheses -Wint-in-bool-context -Wmisleading-indentation)
 
@@ -855,7 +862,6 @@ source_group("Include\\Xtensa" FILES ${HEADERS_XTENSA})
 ## installation
 if(CAPSTONE_INSTALL)
     include(GNUInstallDirs)
-
     install(FILES ${HEADERS_COMMON} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/capstone)
     install(FILES ${HEADERS_INC} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/capstone/inc)
 

CMakeLists.txt

@@ -0,0 +1,11 @@
+MIT License
+
+The scope of this license is the `packages/deb` directory
+
+Copyright (c) 2024 Andrew Quijano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

LICENSES/LICENSE_DEB_PACKAGE.txt

@@ -11,4 +11,3 @@ archive=${libdir}/libcapstone.a
 Libs: -L${libdir} -lcapstone
 Libs.private: -L${libdir} -l:libcapstone.a
 Cflags: -I${includedir} -I${includedir}/capstone
-archs=@CAPSTONE_ARCHITECTURES@

capstone.pc.in

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2024 Andrew Quijano
+# Contact: [email protected]
 ARG VERSION=""
 
 # Run in the root of the repo
@@ -16,7 +19,8 @@ WORKDIR /capstone/
 
 # Using cmake, see BUILDING.md file
 # For debug build change "Release" to "Debug"
-RUN cmake -B build -DCMAKE_BUILD_TYPE=Release -DCAPSTONE_BUILD_SHARED_LIBS=1
+ARG VERSION
+RUN cmake -B build -DCMAKE_BUILD_TYPE=Release -DCAPSTONE_BUILD_SHARED_LIBS=1 -DPROJECT_VERSION=${VERSION} -DCMAKE_INSTALL_PREFIX=/usr
 RUN cmake --build build
 
 # List files before cmake install
@@ -26,6 +30,7 @@ RUN cmake --build build
 RUN mkdir -p /package-root/usr/include/capstone/
 RUN mkdir -p /package-root/usr/lib/pkgconfig/
 RUN mkdir -p /package-root/usr/bin/
+RUN mkdir -p /package-root/usr/share/doc/libcapstone-dev
 
 # Run cmake install
 RUN cmake --install build --prefix /package-root/usr/
@@ -36,18 +41,28 @@ RUN cmake --install build --prefix /package-root/usr/
 # Create DEBIAN directory and control file
 COPY ./packages/deb/control /package-root/DEBIAN/control
 
-# Update capstone.pc file with the correct version and remove archs field
-# Update control file with the correct version
+# Copy documentation over
+COPY ./LICENSES/ /package-root/usr/share/doc/libcapstone-dev/LICENSES/
+COPY ./ChangeLog /package-root/usr/share/doc/libcapstone-dev
+COPY ./CREDITS.TXT /package-root/usr/share/doc/libcapstone-dev
+COPY ./README.md /package-root/usr/share/doc/libcapstone-dev
+COPY ./SPONSORS.TXT /package-root/usr/share/doc/libcapstone-dev
+
+# Generate MD5 checksums for all files and save to DEBIAN/md5sums
+RUN cd /package-root && \
+    find . -type f ! -path './DEBIAN/*' -exec md5sum {} + | sed 's| \./| |' > /package-root/DEBIAN/md5sums
+
+# Update control file with the correct information
 ARG VERSION
+RUN INSTALLED_SIZE=$(du -sk /package-root | cut -f1) && \
+    sed -i "s/^Installed-Size:.*/Installed-Size: ${INSTALLED_SIZE}/" /package-root/DEBIAN/control
 RUN sed -i "s/^Version:.*/Version: ${VERSION}/" /package-root/DEBIAN/control
-RUN sed -i "s/^Version:.*/Version: ${VERSION}/" /package-root/usr/lib/pkgconfig/capstone.pc
-RUN sed -i "/^archs=/d" /package-root/usr/lib/pkgconfig/capstone.pc
 
 # Add triggers script to run ldconfig after installation
 COPY ./packages/deb/triggers /package-root/DEBIAN/triggers
 
 # Build the package
-RUN fakeroot dpkg-deb --build /package-root /libcapstone-dev.deb
+RUN fakeroot dpkg-deb --build /package-root /libcapstone-dev_${VERSION}_amd64.deb
 
 # The user can now extract the .deb file from the container with something like
 # docker run --rm -v $(pwd):/out packager bash -c "cp /libcapstone-dev.deb /out"

packages/deb/Dockerfile

@@ -1,7 +1,26 @@
-Incomplete Debian package implementation.
-It can be used to generate an easily installable Capstone, but misses a lot of
-mandatory things to add it in the Debian repos (`debian/control` is incomplete, no dependencies added etc.).
+# Capstone Docker packaging
 
-You can build the package by dispatching the `Build Debian Package` workflow or executing the commands in the `Dockerfile`.
-It assumes the current commit is tagged and `"$(git describe --tags --abbrev=0)"` returns a valid version number.
-The package is uploaded as artifact.
+This assumes your working directory is in the `packages/deb/` directory. 
+To build a Debian package for Capstone, run the script, where `<tag-name>` is going to be the version 
+attached to both the `capstone.pc` file and the Debian package itself. The version is expected to be compliant with Debian versioning (a major/minor/patch), e. g. `5.0.4`. Debian versions can also support values to indicate pre-release, e. g. `6.0.0-Alpha1`.
+
+**Note**: if a value such as `6.0.0-Alpha1` is provided, the major/minor/patch number is extracted for `capstone.pc`, which would have version `6.0.0`, but the Debian package would have the full version name on the control file.
+
+**Note**: Currently the package is hard coded to the `amd64` architecture. Independently on what machine you built it. Also see [issue #2537](https://github.com/capstone-engine/capstone/issues/2537).
+
+```bash
+./setup.sh <tag-name>
+```
+
+The output Debian file would be in the form `libcapstone-dev_<tag-version>_amd64.deb`, as to match what would be expected in a standard Debian library package.
+
+To confirm the necessary libraries and `capstone.pc` is filled correctly, there exists a `check_capstone.sh` script to confirm `libcapstone-dev` was built correctly. 
+
+If you want to check the contents of the Debian package, use the following:
+```bash
+# Check the DEBIAN/ folder
+dpkg-deb -e libcapstone-dev_<tag-version>_amd64.deb ./unpacked
+
+# Check the content of the package, EXCEPT the DEBIAN/ folder
+dpkg-deb -x libcapstone-dev_<tag-version>_amd64.deb ./unpacked
+```

packages/deb/README.md

@@ -1,9 +1,13 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2024 Andrew Quijano
+# Contact: [email protected]
+
 #!/bin/bash
+set -eu
 
-# Usage: ./check_capstone_pc.sh <path_to_deb_file> <expected_version>
+# Usage: ./check_capstone_pc.sh <path_to_deb_file>
 
 DEB_FILE=$1
-EXPECTED_VERSION=$2
 
 # Check if the deb file exists
 if [[ ! -f "$DEB_FILE" ]]; then
@@ -17,46 +21,24 @@ TEMP_DIR=$(mktemp -d)
 # Extract the deb file
 dpkg-deb -x "$DEB_FILE" "$TEMP_DIR"
 
-# Path to the capstone.pc file
-CAPSTONE_PC="$TEMP_DIR/usr/lib/pkgconfig/capstone.pc"
-
 # Check if the capstone.pc file exists
+CAPSTONE_PC="$TEMP_DIR/usr/lib/x86_64-linux-gnu/pkgconfig/capstone.pc"
 if [[ ! -f "$CAPSTONE_PC" ]]; then
   echo "capstone.pc file not found in the package!"
   rm -rf "$TEMP_DIR"
   exit 1
 fi
 
-# Remove leading 'v' if present, e. g. v1.5.1 -> 1.5.1
-if [[ "$EXPECTED_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-    EXPECTED_VERSION=${EXPECTED_VERSION:1}
-fi
-
-# Check if the version follows the format X.Y.Z, e. g. 1.5.1 or 1.9.1
-if [[ ! "$EXPECTED_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-    echo "ERROR: Version must be in the format X.Y.Z"
-    exit 1
-fi
-
-
-# Check the version in the capstone.pc file
-ACTUAL_VERSION=$(grep "^Version:" "$CAPSTONE_PC" | awk '{print $2}')
-if [[ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]]; then
-  echo "Version mismatch! Expected: $EXPECTED_VERSION, Found: $ACTUAL_VERSION"
-  rm -rf "$TEMP_DIR"
-  exit 1
-fi
-
 # Check if libcapstone.a is included in the package
-LIBCAPSTONE_A="$TEMP_DIR/usr/lib/libcapstone.a"
+LIBCAPSTONE_A="$TEMP_DIR/usr/lib/x86_64-linux-gnu/libcapstone.a"
 if [[ ! -f "$LIBCAPSTONE_A" ]]; then
   echo "libcapstone.a not found in the package!"
   rm -rf "$TEMP_DIR"
   exit 1
 fi
 
 # Check if libcapstone.so is included in the package
-LIBCAPSTONE_SO="$TEMP_DIR/usr/lib/libcapstone.so"
+LIBCAPSTONE_SO="$TEMP_DIR/usr/lib/x86_64-linux-gnu/libcapstone.so"
 if [[ ! -f "$LIBCAPSTONE_SO" ]]; then
   echo "libcapstone.so not found in the package!"
   rm -rf "$TEMP_DIR"

packages/deb/check_capstone.sh

@@ -1,8 +1,25 @@
-Package: capstone
+Package: libcapstone-dev
+Source: capstone
 Version: <version-placeholder>
-Architecture: all
+Architecture: amd64
 Maintainer: Rot127 <[email protected]>
-Description: Capstone is a lightweight multi-platform, multi-architecture disassembly framework. 
- Capstone supports the following frameworks; 
- Alpha, BPF, Ethereum VM, HPPA, LoongArch, M68K, M680X, Mips, MOS65XX, PPC, RISC-V(rv32G/rv64G), 
- SH, Sparc, SystemZ, TMS320C64X, TriCore, Webassembly, XCore and X86.
+Original-Maintainer: Debian Security Tools <[email protected]>
+Installed-Size: <size-in-kb>
+Depends: libc6 (>= 2.2.5)
+Section: libdevel
+Priority: optional
+Multi-Arch: same
+Homepage: https://www.capstone-engine.org/
+Description: lightweight multi-architecture disassembly framework - devel files
+ Capstone is a lightweight multi-platform, multi-architecture disassembly
+ framework. These are the development headers and libraries.
+ Features:
+ - Support hardware architectures: AArch64, ARM, Alpha, BPF, EVM, HPPA, LongArch, M680X, M68K, MOS65XX, Mips, PowerPC, RISCV, SH, Sparc, SystemZ, TMS320C64x, TriCore, WASM, x86, XCore, Xtensa.
+ - Clean/simple/lightweight/intuitive architecture-neutral API.
+ - Provide details on disassembled instructions (called "decomposer" by some
+ others).
+ - Provide some semantics of the disassembled instruction, such as list of
+ implicit registers read & written.
+ - Thread-safe by design.
+ - Special support for embedding into firmware or OS kernel.
+ - Distributed under the open source BSD license.

packages/deb/control

@@ -1,3 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2024 Andrew Quijano
+# Contact: [email protected]
+
 # !/bin/bash
 set -eu
 
@@ -33,10 +37,10 @@ if [[ "$version" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
     version=${version:1}
 fi
 
-# Check if the version follows the format X.Y.Z, e. g. 1.5.1 or 1.9.1
-if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-    echo "ERROR: Version must be in the format X.Y.Z"
-    exit 1
+# Check if the version follows the format for Debian Packages
+if [[ ! "$version" =~ ^[0-9]+(.[0-9]+)*(-[A-Za-z0-9]+)?$ ]]; then
+  echo "ERROR: Version must be in a valid Debian package format"
+  exit 1
 fi
 
 # Now build the packager container from that
@@ -45,7 +49,7 @@ docker build -f ./packages/deb/Dockerfile -t packager --build-arg VERSION="${ver
 popd
 
 # Copy deb file out of container to host
-docker run --rm -v $(pwd):/out packager bash -c "cp /libcapstone-dev.deb /out"
+docker run --rm -v $(pwd):/out packager bash -c "cp /*.deb /out"
 
 # Check which files existed before and after 'make install' was executed.
 # docker run --rm -v $(pwd):/out packager bash -c "cp /before-install.txt /out"