Import LinuxCNC source tree

debian/README.source

@@ -0,0 +1,178 @@
+# Debian packaging of LinuxCNC
+
+## Introduction
+
+LinuxCNC is packaged in two different ways:
+
+ 1. a simple way for the builds on the LinxuCNC buildbot
+    CI system (<http://buildbot.linuxcnc.org>), and
+ 2. a different (more complicated) way for official debian.org packages.
+
+Packaging by the LinuxCNC CI system is not covered in this document, see
+<http://linuxcnc.org/docs/devel/html/code/building-linuxcnc.html#_building_debian_packages>
+for a brief description on that.
+
+This document describes the official packaging for debian.org.
+Packaging of LinuxCNC for debian.org is split between:
+
+linuxcnc.git (in <https://github.com/LinuxCNC/linuxcnc.git>)::
+  This is the regular LinuxCNC repository. This already provides instructions
+  to build a Debian package in the subdirectory "debian/".
+  Branches for this repository reflect the ongoing developments for LinuxCNC.
+linuxcnc-gbp.git (in <https://github.com/LinuxCNC/linuxcnc-gbp.git>)::
+  This repository has the same content as the release version, just that
+  branches now describe the release of Debian that the package shall be
+  used for. In particular, the script debian/configure was already executed.
+  Default uploads go to Debian unstable, aka "sid", which needs
+  to be stated in the file debian/changelog. Also the version number of the
+  uploads to Debian are slightly different, so that multiple revisions of the
+  Debian package is possible for the same release of LinuxCNC.
+```
+$ git branch
+* debian/unstable
+  upstream
+```
+
+## debian/copyright
+
+Automated tools to check licenses within the source tree will likely find
+CC-2.5 referenced. But this refers only to some image files that were
+not adopted by the source tree, only the README describing them was
+intentionally left unchanged.
+
+
+## Build a new DSC for upload to debian.org
+
+
+### Make the new orig tarball
+
+Do this step in `linuxcnc.git`.
+
+```
+git checkout ${COMMIT}  # check out the commit you want
+git reset --hard
+git clean -fdx .
+VERSION=$(head -n1 debian/changelog |cut -f2 -d' ' | tr -d "()" | sed -e 's/^[0-9]://' )
+```
+If you are not uploading the exact same version of what is in the release tarball,
+then also specify the git tag as part of the version:
+
+```
+VERSION=$(git log --date=format:%Y%m%d --pretty=${VERSION}+git%cd.%h| head -n1)
+```
+Inspect the version and create the file VERSION.
+```
+echo ${VERSION} | tee VERSION
+```
+
+We use `--exclude=.git` instead of `--exclude-vcs` because the linuxcnc
+git repo uses .gitignore to keep otherwise-empty directories around,
+and the build system is too lazy to mkdir them as needed.
+
+```
+tar --create --xz --exclude=.git --exclude=.github --transform "flags=r;s|^./|linuxcnc-${VERSION}/|" --file ../debian-packaging/linuxcnc_${VERSION}.orig.tar.xz .
+```
+
+### Start the new gbp version
+
+Do this step in `linuxcnc-gbp.git`.
+
+Import the new orig tarball into gbp `upstream` branch, but *don't*
+let gbp auto-merge it into `debian/unstable`.
+
+```
+git fetch
+
+git checkout upstream
+git merge --ff-only origin/upstream
+
+git checkout debian/unstable
+git merge --ff-only origin/debian/unstable
+
+gbp import-orig --no-merge ../linuxcnc_${VERSION}.orig.tar.xz
+git merge --no-commit upstream
+# verify contents of debian/*, especially changelog
+git commit
+```
+
+
+### Update the debian/ files
+
+Do this step in `linuxcnc-gbp.git`.
+
+Run `debian/configure` in a clean, minimal instance of the distro we're building for:
+
+```
+export IMAGE="debian:bookworm"
+docker pull ${IMAGE}
+docker run --rm --interactive --tty --volume ${PWD}:${PWD} --workdir ${PWD} ${IMAGE}
+apt-get --quiet update
+apt-get --quiet --yes install --no-install-recommends --no-install-suggests \
+    git \
+    lsb-release \
+    python3
+debian/configure
+exit
+```
+
+Update d/changelog (preserve entries from previous debs), include "New
+upstream version", close any fixed bugs:
+
+```
+gbp dch
+dch -e
+```
+
+Commit all changes to the debian/ directory:
+
+```
+git commit
+```
+
+### Test the new debian package
+
+`gbp buildpackage` should work in a minimal installation of the target distro:
+
+```
+docker run --rm --interactive --tty --volume ${PWD}:${PWD} --workdir ${PWD} ${IMAGE}
+apt-get --quiet update
+apt-get --quiet --yes install --no-install-recommends --no-install-suggests git-buildpackage
+apt-get --quiet --yes build-dep .
+gbp buildpackage --build=full --no-sign
+```
+
+In addition to `--build=full` (build source, architecture-specific,
+and architecture-independent packages), `--build=any`
+(build architecture-specific packages) and `--build=all` (build
+architecture-independent packages) should also build from scratch in a
+clean minimal environment.
+
+(The docker build environment described above is just one option, other
+possibilities are cowbuilder, pbuilder, etc., etc.)
+
+Run lintian to verify the build products:
+
+```
+apt-get --quiet --yes install lintian
+lintian -i ../linuxcnc_*.changes
+```
+
+
+### Release
+
+```
+gbp dch --release
+gbp tag
+
+git push --tags origin debian/unstable upstream
+```
+
+Build & sign the dsc:
+
+`dpkg-buildpackage --build=source -k${KEY_ID}`
+
+
+## How to contribute
+
+LinuxCNC does not have a representation on salsa.debian.org.
+Please join us on https://github.com/LinuxCNC/linuxcnc/ .