Debian packaging of LinuxCNC
============================

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.

Steps
-----

The following steps were performed to transform Upstream's git repository
into
 - a source tarball and
 - a debian subdirectory
for Debian's main distribution.

LinuxCNC is used across a wide span of releases, now supporting from
Squeeze up to the latest version of Ubuntu. Not too many changes are
required for Debian unstable.

1. Generate the source tarball, This will use the version as specified
   in the first line of the debian/changelog file. And maybe remove
   anything outdated, just to avoid confusions:

   If this is not the original tarball but an interim git tag/snapshot,
   then set the version in debian/changelog. For git checkout, the
   version stated in debian/changelog receives the suffix +gitYYYYMMDD.githash

   VERSION=$(head -n1 debian/changelog |cut -f2 -d' ' | tr -d "()" | sed -e 's/^[0-9]://' )

   If the current source tree is not the regular release but git checkout also
   create the fitting tarball:

   echo -n "I: Version: $VERSION -> "
   VERSION=$(git log --date=format:%Y%m%d --pretty=${VERSION}+git%cd.%h| head -n1)
   echo $VERSION
   foldername=$(basename $(pwd))
   if [ -d debian/patches ]; then quilt pop -a && rm -rf .pc; fi
   echo "I: taring up CWD into linuxcnc_${VERSION}.orig.tar.xz - this will take a minute or two"
   (cd .. && tar --exclude=.git* --exclude=.pc -cJf "linuxcnc_${VERSION}.orig.tar.xz" "$foldername")
   du -sh ../$foldername
   echo "I: Please inspect with 'tar Jtf ../linuxcnc_${VERSION}.orig.tar.xz'"

2. Prepare shell to work in temp directory

   export VERSION
   export WORKDIR=$(mktemp -d)
   mv "../linuxcnc_${VERSION}.orig.tar.xz" ${WORKDIR}/ && \
   pushd $WORKDIR && bash
   echo -n "I: Now working in "; pwd

3. Unpack

   echo -n "I: Unpacking source tree to build from newly generated orig.tar.xz"
   tar xJvf linuxcnc_*.orig.tar.xz
   cd linuxcnc

4. Configure debian directory for the "uspace" packages that are
   prepared for the Non-RTAI but preempt realtime kernels that are
   distributed with Debian.

   debian/configure

5. Slightly adapt for upload to d/unstable

   mkdir -p debian/source
   echo "3.0 (quilt)" > debian/source/format

   # dch is from the devscripts package
   dch -b -m -v "$VERSION" --distribution unstable  "New upstream version."

6a. build Debian package if in doubt - optional

   dpkg-buildpackage

6b. build Debian source package, which is what is uploaded to Debian upon acceptance and for updates

   dpkg-buildpackage -S

7. test build in cowbuilder

   sudo cowbuilder --update
   sudo cowbuilder --build ../linuxcnc_*.dsc

8. check that nothing avoidable slipped through

   lintian -i /var/cache/pbuilder/results/linuxcnc_*.changes

8. get all the files just created

   exit
   mv ${WORKDIR}/linuxcnc_* ..

Above sketched differences are not impeding routine workflows of Debian
packaging. For instance we found that the routine-update script (from the
Debian Science team) deals with these adaptations just fine.


How to contribute
-----------------

LinuxCNC does not have a representation on salsa.debian.org. 
Please join us on https://github.com/LinuxCNC/linuxcnc/ .