From b6c95078de756747bead0c500bcb26c809ef8b75 Mon Sep 17 00:00:00 2001 From: futurejones Date: Tue, 23 Nov 2021 18:31:06 +0900 Subject: [PATCH] Add Debian packaging policy and sample package documents. --- platforms/Linux/DEB/Docs/debian_policy.md | 51 ++++++++++ .../Linux/DEB/Docs/sample_package_test.md | 96 +++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 platforms/Linux/DEB/Docs/debian_policy.md create mode 100644 platforms/Linux/DEB/Docs/sample_package_test.md diff --git a/platforms/Linux/DEB/Docs/debian_policy.md b/platforms/Linux/DEB/Docs/debian_policy.md new file mode 100644 index 00000000..9041a514 --- /dev/null +++ b/platforms/Linux/DEB/Docs/debian_policy.md @@ -0,0 +1,51 @@ +# Official Debian Packaging Policy +*The purpose of this document is to outline what is required to have the `Swift Toolchain` packages accepted into the official Debian Repositories.* + +#### Note: About Official Ubuntu Repositories. +For a package to be accepted into the official `Ubuntu` repositories first the package must be accepted and approved for Debian. Packages are then synced from Debian to the Ubuntu repositories. + +### Intent To Package +The first step in getting a package approved is to file an `ITP` (Intent To Package). +An `ITP` is a special bug report saying that you want to package some product. +You file an `ITP` by using the reportbug tool and specifying “wnpp” as the package you want to report a bug against. + +*NOTE:- an `ITP` for `swiftlang` was filed in 2015 [#788327](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=788327). It doesn't appear anything other than filing the `ITP` was done.* + +### Sponsorship +Unless you are an accepted Debian Developer you cannot upload to the Debian Repository directly. You have to package your product and then ask for a `sponsor` on the `debian-mentors mailing list`. The `sponser` will check your packages and decide whether they are ready to be accepted into Debian. The `sponser` will then upload the packages and add them to Debian. +Once it is proven that you are able to create proper new packages and that you are willing to maintain them, you can then become a Debian developer. + +### Debian Developer +For more information about being a Debian Developer please read the [Debian Developer's Reference](http://www.debian.org/doc/developers-reference/) + +### Debian Distributions Timeline +Debian is divided into three distributions: `stable, testing and unstable`. Whenever a new package is added, or an existing package is updated, it goes into `unstable`. Once it has been in `unstable` for ten days without revealing serious bugs, it automatically moves into `testing`. When the release manager decides it's time for a new release, he declares the `testing` distribution as `frozen`. This means that no new packages can be added, and no existing ones may be updated. Only outstanding bugs may be fixed. Once he thinks that `testing` is ready to be released, it becomes `stable` and a new `testing` distribution is added. + +### Package Testing +New packages need to be thoroughly tested for installation and errors before they can be uploaded for inclusion. + +This should be done with sequences such as the following: +* install the previous version (if needed). +* upgrade it from the previous version. +* downgrade it back to the previous version (optional). +* purge it. +* install the new package. +* remove it. +* install it again. +* purge it. + +#### Testing With Lintian +`lintian` is one of the main tools used to test DEB packages for errors. + +*Lintian dissects Debian packages and reports bugs and policy violations. It contains automated checks for many aspects of Debian policy as well as some checks for common errors.* + +See here for [Testing a Sample Swift DEB Package with Lintian](sample_package.md) + +### Reference Documents + +* [Debian Policy Manual](https://www.debian.org/doc/debian-policy/) +* [Debian New Maintainers' Guide](https://www.debian.org/doc/manuals/maint-guide/) +* [How Software Producers Can Distribute Their Products Directly in DEB Format](https://www.debian.org/doc/manuals/distribute-deb/distribute-deb.html) +* [Debian Mailing Lists](https://www.debian.org/MailingLists/) +* [Debian New Members Corner](https://www.debian.org/devel/join/newmaint) +* [Debian bug tracking system](https://www.debian.org/Bugs/) diff --git a/platforms/Linux/DEB/Docs/sample_package_test.md b/platforms/Linux/DEB/Docs/sample_package_test.md new file mode 100644 index 00000000..c9fe165e --- /dev/null +++ b/platforms/Linux/DEB/Docs/sample_package_test.md @@ -0,0 +1,96 @@ +### Sample Package Build and Test +*Test build of a Ubuntu Focal .deb package for compliance testing.* +#### Swift Toolchain Source +```bash +https://download.swift.org/swift-5.5.1-release/ubuntu2004/swift-5.5.1-RELEASE/swift-5.5.1-RELEASE-ubuntu20.04.tar.gz +``` +#### Control File + +```yaml +# control file +Package: swiftlang +Version: 5.5.1 +Iteration: 01-ubuntu-focal +License: Apache License Version 2.0 +Architecture: amd64 +Maintainer: Swift Infrastructure +Depends: binutils, git, gnupg2, libc6-dev, libcurl4, libedit2, libgcc-9-dev, python3, libpython3.8, libsqlite3-0, libstdc++-9-dev, libxml2, libz3-dev, pkg-config, tzdata, zlib1g-dev +Section: devel +Priority: optional +Homepage: https://swift.org +Description: The Swift Programming Language. + Swift is a general-purpose programming language built using a modern approach to safety, performance, and software design patterns. +``` +#### Package Directory Structure +```bash +# download and unpack swift toolchain +wget https://download.swift.org/swift-5.5.1-release/ubuntu2004/swift-5.5.1-RELEASE/swift-5.5.1-RELEASE-ubuntu20.04.tar.gz +tar xzf swift-5.5.1-RELEASE-ubuntu20.04.tar.gz + +# add the DEBIAN directory and control file +# the directory structure should be as follows +swift-5.5.1-RELEASE-ubuntu20.04 + ├ DEBIAN + │ └ control + └ usr + └ ... swift toolchain +``` +#### Build DEB Package +Build the test package is using `fakeroot` and `dpkg-deb` tools. +```bash +# build DEB package from toolchain directory +fakeroot dpkg-deb --build swift-5.5.1-RELEASE-ubuntu20.04/ + dpkg-deb: building package 'swiftlang' in 'swift-5.5.1-RELEASE-ubuntu20.04.deb'. + +``` +#### Testing Package With Lintian + +```bash +lintian -i -v swift-5.5.1-RELEASE-ubuntu20.04.deb +``` +```swift +// partial output of test results +N: Using profile ubuntu/main. +N: Starting on group swiftlang/5.5.1 +N: Unpacking packages in group swiftlang/5.5.1 +N: Finished processing group swiftlang/5.5.1 +N: ---- +N: Processing binary package swiftlang +N: (version 5.5.1, arch amd64) ... +E: swiftlang: binary-or-shlib-defines-rpath usr/bin/lldb /home/build-user/build/buildbot_linux/llvm-linux-x86_64/lib +N: +N: The binary or shared library sets RPATH or RUNPATH. This overrides the +N: normal library search path, possibly interfering with local policy and +N: causing problems for multilib, among other issues. +N: +N: The only time a binary or shared library in a Debian package should set +N: RPATH or RUNPATH is if it is linked to private shared libraries in the +N: same package. In that case, place those private shared libraries in +N: /usr/lib/. Libraries used by binaries in other packages should +N: be placed in /lib or /usr/lib as appropriate, with a proper SONAME, in +N: which case RPATH/RUNPATH is unnecessary. +N: +N: To fix this problem, look for link lines like: +N: gcc test.o -o test -Wl,--rpath,/usr/local/lib +N: or +N: gcc test.o -o test -R/usr/local/lib +N: and remove the -Wl,--rpath or -R argument. You can also use the chrpath +N: utility to remove the RPATH. +N: +N: Refer to https://wiki.debian.org/RpathIssue for details. +N: +N: Severity: error +N: +N: Check: binaries +N: +E: swiftlang: binary-or-shlib-defines-rpath usr/bin/lldb-argdumper /home/build-user/build/buildbot_linux/llvm-linux-x86_64/lib +E: swiftlang: binary-or-shlib-defines-rpath usr/bin/lldb-server /home/build-user/build/buildbot_linux/llvm-linux-x86_64/lib +E: swiftlang: binary-or-shlib-defines-rpath usr/bin/plutil /home/build-user/build/buildbot_linux/swift-linux-x86_64/lib/swift/linux +E: swiftlang: binary-or-shlib-defines-rpath usr/lib/clang/10.0.0/lib/linux/libclang_rt.memprof-x86_64.so /home/build-user/build/buildbot_linux/llvm-linux-x86_64/lib +E: swiftlang: binary-or-shlib-defines-rpath usr/lib/clang/10.0.0/lib/linux/libclang_rt.ubsan_minimal-x86_64.so /home/build-user/build/buildbot_linux/llvm-linux-x86_64/lib +E: swiftlang: binary-or-shlib-defines-rpath usr/lib/liblldb.so.10.0.0git /home/build-user/build/buildbot_linux/llvm-linux-x86_64/lib +E: swiftlang: changelog-file-missing-in-native-package +``` +This initial testing shows there are a number errors and warnings that will need to be addressed before `swiftlang` packages can be accepted into the official Debian/Ubuntu repositories. + +For full details of the test output please refer to this [Swift Bug Report SR-15515](https://bugs.swift.org/browse/SR-15515) \ No newline at end of file