Skip to content

Add Debian packaging policy and sample package documents. #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Add Debian packaging policy and sample package documents. #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions platforms/Linux/DEB/Docs/debian_policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/)
96 changes: 96 additions & 0 deletions platforms/Linux/DEB/Docs/sample_package_test.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <[email protected]>
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/<package>. 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)