Differences between revisions 6 and 22 (spanning 16 versions)
Revision 6 as of 2021-06-03 04:26:48
Size: 6047
Editor: PaulWise
Comment: rewording/reordering after discussion with helmut
Revision 22 as of 2021-10-07 02:27:52
Size: 9084
Editor: PaulWise
Comment: mention debci and salsa CI hardware
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
This page documents the approximate procedure for creating a new port and getting it included into Debian. It is a work in progress and is based on the [[PortTemplate|port template]] wiki page. This is an aspirational document describing the most ideal procedure for creating a new port and getting it included into Debian. Since every port will have different circumstances, the procedure may differ for your port, but the best way to do it should be documented below. It is a work in progress and is based on the [[PortTemplate|port template]] wiki page.
Line 3: Line 3:
/!\ Do not skip any of the steps. /!\ It is best to not skip any of the steps.
Line 5: Line 5:
/!\ Complete each step before moving to later steps. /!\ It is best to complete each item before moving to later steps.
Line 7: Line 7:
Assemble a team of people working on the port and find a financial sponsor to support the team's work. <<TableOfContents>>
Line 9: Line 9:
Identify related ports and ISAs, decide that the port is worth creating and detail the reasons why. = Preparation =
Line 11: Line 11:
Decide on the GNU triplet, [[Multiarch/Tuples|Debian multiarch tuple]], Debian architecture name, the name that end-users will use for the architecture and other [[ArchitectureSpecificsMemo|details]] of the architecture and ABI.   * Assemble a team of people working on the port and find a financial sponsor to support the team's work.
Line 13: Line 13:
Discuss the port with the community. Please send an email to the DebianList:FIXME mailing list. If the port is related to some other architectures, ensure you CC the mailing list for the architecture family. Also join the #debian-bootstrap and #debian-ports [[IRC]] channels. = Upstreaming =
Line 15: Line 15:
Finalise the architecture details, especially including the ABI and CPU baseline requirements.   * Decide on the [[ArchitectureSpecificsMemo|architecture ABI details]] and the GNU triplet. A different GNU triplet is required for each ABI, which includes bitness, endianness, soft/hard-float, calling convention, or whether object files can be inter-linked.
Line 17: Line 17:
Prepare patches supporting the port and get the necessary changes included upstream for [[https://savannah.gnu.org/projects/config|GNU config]] ([[https://git.savannah.gnu.org/cgit/config.git/tree/config.guess|instructions]]), [[https://www.gnu.org/software/binutils/|binutils]], gcc ([[https://gcc.gnu.org/contribute.html|instructions]], gdb ([[https://www.gnu.org/software/gdb/contribute/|instructions]]), qemu ([[https://www.qemu.org/contribute/|instructions]]), glibc ([[https://sourceware.org/glibc/wiki/Contribution%20checklist|instructions]]), linux ([[https://kernelnewbies.org/|info]]) projects and any other upstream projects that you need to modify.   * Register accounts for each team member on the bug trackers and subscribe to the mailing lists for upstream projects: [[https://savannah.gnu.org/projects/config|GNU config]], [[https://www.gnu.org/software/binutils/|binutils]], [[https://gcc.gnu.org/|gcc]], [[https://www.gnu.org/software/gdb/|gdb]], [[https://www.qemu.org/|qemu]], kernel (such as [[https://www.kernel.org/|Linux]]), and libc (such as [[https://sourceware.org/glibc/|glibc]])
Line 19: Line 19:
Prepare patches supporting the port in [[HelmutGrohne/rebootstrap|rebootstrap]], dpkg and other Debian-specific packages.   * Prepare kernel and toolchain patches supporting the port and get the necessary changes included into these upstream projects: [[https://savannah.gnu.org/projects/config|GNU config]] ([[https://git.savannah.gnu.org/cgit/config.git/tree/config.guess|instructions]]), [[https://www.gnu.org/software/binutils/|binutils]], gcc ([[https://gcc.gnu.org/contribute.html|instructions]]), gdb ([[https://www.gnu.org/software/gdb/contribute/|instructions]]), the kernel (such as Linux ([[https://kernelnewbies.org/|info]])) and the libc (such as glibc ([[https://sourceware.org/glibc/wiki/Contribution%20checklist|instructions]])) (in that order)
Line 21: Line 21:
Use your modified rebootstrap, the other patches and manual [[DebianBootstrap|bootstrapping]] to build all of build-essential.   * If hardware supporting your port is not yet available or your hardware or FPGA softcore or software model is quite slow, prepare patches for the appropriate simulator/emulator upstream project (such as qemu ([[https://www.qemu.org/contribute/|instructions]])). If you do not need this, it will still be very useful to complete at some point, so consider completing it later on.
Line 23: Line 23:
Keep working on the bootstrap process until all of build-essential is installable with debootstrap. = Downstreaming =
Line 25: Line 25:
Continue building as many packages as you can using the new build-essential packages.   * Identify related ports and ISAs, decide that the port is worth creating and detail the reasons why.
Line 27: Line 27:
Get any remaining changes included into the upstream projects that you have modified.   * Register accounts for each team member on the [[DebianWiki|Debian wiki]] ([[DebianWiki/EditorQuickStart#Account|registration]]) and [[Salsa]] ([[https://salsa.debian.org/users/sign_up|register]]).
Line 29: Line 29:
Get any necessary changes included into dpkg ([[Teams/Dpkg/FAQ#new-arch|instructions]]), rebootstrap and other projects involved in the bootstrap process.   * [[https://www.oftc.net/Services/#register-your-account|Register]] and [[https://services.oftc.net/|verify]] accounts for each team member on the [[https://www.oftc.net/|OFTC]] IRC chat network and join the #debian-bootstrap, #debian-ports and other Debian [[IRC]] channels.
Line 31: Line 31:
[[Ports|Register the port]] on the Debian wiki, replace "example" throughout the page with the chosen architecture details and fill out as many details as you have.   * Discuss the port with the community. Please send an email to the DebianList:debian-devel mailing list. If the port is related to some other architectures, ensure you CC the mailing list for the architecture family. Also join the #debian-bootstrap and #debian-ports [[IRC]] channels.
Line 33: Line 33:
Summarise the details of the architecture and ABI on the [[ArchitectureSpecificsMemo#Summary|arch summary wiki page]].   * Finalise the architecture details, especially including the ABI and CPU baseline requirements.
Line 35: Line 35:
Setup communication channels for the architecture. Use the architecture family as the name of any communication channels you create, just in case additional related architectures are created later. A [[https://www.debian.org/MailingLists/HOWTO_start_list|mailing list]] and [[IRC#How_to_create_a_new_.23debian-.2A_channel|IRC channel]] are recommended.   * Get any necessary changes included into dpkg ([[Teams/Dpkg/FAQ#new-arch|instructions]]), to get the new Debian architecture name supported (which is the name that end-users will use for the architecture), this requires having the [[ArchitectureSpecificsMemo|architecture ABI details]] clear, the [[Multiarch/Tuples|Debian multiarch tuple]] is derived from the Debian architecture tuple.
Line 37: Line 37:
Add your architecture to the [[Teams/Debbugs/ArchitectureTags|bugs arch usertags page]]. = Bootstrap =
Line 39: Line 39:
[[https://www.ports.debian.org/contacts|Get]] the port included amongst the unofficial ports.   * Prepare patches supporting the port in [[HelmutGrohne/rebootstrap|rebootstrap]] and other Debian-specific packages.
Line 41: Line 41:
[[https://www.debian.org/devel/buildd/|Setup unofficial buildd servers]] for the port, either in qemu or hardware.   * Use your modified rebootstrap, the other patches and manual [[DebianBootstrap|bootstrapping]] to build all of build-essential.
Line 43: Line 43:
Include the port on the [[https://www.debian.org/ports/|ports list on the Debian website]] and add the end-user name for the port to the [[https://salsa.debian.org/webmaster-team/webwml/-/blob/master/english/releases/arches.data|website arches data]]. If you create a page on the website, create one named after the architecture family, just in case additional related architectures are created later.   * Keep working on the bootstrap process until all of build-essential is installable with debootstrap.
Line 45: Line 45:
Monitor build failures ([[https://buildd.debian.org/status/architecture.php|1]] [[https://udd.debian.org/cgi-bin/ftbfs.cgi|2]]) and continually fix issues.   * Continue building as many packages as you can using the new build-essential packages.
Line 47: Line 47:
Donate hardware for the [[https://gcc.gnu.org/wiki/CompileFarm|GCC compile farm]].   * Get any remaining changes included into the upstream projects that you have modified.
Line 49: Line 49:
Setup porterboxen for package maintainers to login to and port packages.   * Get any necessary changes included into rebootstrap and other projects involved in the bootstrap process.
Line 51: Line 51:
Optionally, donate hardware for [[https://debomatic.github.io/|debomatic]]. = Unofficial port =
Line 53: Line 53:
Port the [[https://www.debian.org/devel/debian-installer/|Debian installer]] so that it works on the hardware you have available.   * [[Ports|Register the port]] on the Debian wiki, replace "example" throughout the page with the chosen architecture details and fill out as many details as you have.
Line 55: Line 55:
Use the Debian installer to install Debian on the hardware you have available.   * Summarise the details of the architecture and ABI on the [[ArchitectureSpecificsMemo#Summary|arch summary wiki page]].
Line 57: Line 57:
Write some [[https://wiki.debian.org/InstallingDebianOn|documentation about installing the arch on the hardware]] you have installed.   * Setup communication channels for the architecture. Use the architecture family as the name of any communication channels you create, just in case additional related architectures are created later. A [[https://www.debian.org/MailingLists/HOWTO_start_list|mailing list]] and [[IRC#How_to_create_a_new_.23debian-.2A_channel|IRC channel]] are recommended.
Line 59: Line 59:
Submit [[https://www.debian.org/releases/stable/amd64/ch05s04#submit-bug|installation reports]] for the hardware you have installed.   * Add your architecture to the [[Teams/Debbugs/ArchitectureTags|bugs arch usertags page]].
Line 61: Line 61:
Submit some [[https://wiki.debian.org/Hardware/Database|hardware probes]] for the hardware you have installed.   * [[https://www.ports.debian.org/contacts|Get]] the port included amongst the unofficial ports.
Line 63: Line 63:
Grow the hardware ecosystem until it satisfies the [[https://dsa.debian.org/ports/hardware-requirements/|requirements for an official port]].   * [[https://www.debian.org/devel/buildd/|Setup unofficial buildd servers]] for the port, either in qemu or hardware.
Line 65: Line 65:
Improve the port until it satisfies the [[https://ftp-master.debian.org/archive-criteria.html|criteria for being included in the main archive]].   * Include the port on the [[https://www.debian.org/ports/|ports list on the Debian website]] and add the end-user name for the port to the [[https://salsa.debian.org/webmaster-team/webwml/-/blob/master/english/releases/arches.data|website arches data]]. If you create a page on the website, create one named after the architecture family, just in case additional related architectures are created later.
Line 67: Line 67:
Donate hardware for the official buildds and co-ordinate with [[Teams/DSA|the Debian sysadmins]] to setup the hardware in Debian hosting locations.   * Monitor build failures ([[https://buildd.debian.org/status/architecture.php|1]] [[https://udd.debian.org/cgi-bin/ftbfs.cgi|2]]) and continually fix issues.
Line 69: Line 69:
Add quality assurance for the port for [[https://reproducible-builds.org/|Reproducible Builds]], [[https://ci.debian.net/doc/|Debian CI]], and [[https://piuparts.debian.org/|piuparts]] (doesn't yet support non-x86 ports) and other [[qa.debian.org|Debian QA efforts]].   * Optionally, donate hardware for the [[https://gcc.gnu.org/wiki/CompileFarm|GCC compile farm]]. It is recommended to do this so that people outside Debian also have access to hardware for testing toolchains or other software on your port.
Line 71: Line 71:
Add support for the port to the [[https://www.debian.org/devel/debian-live/|live images]] and [[Cloud|cloud]] images if appropriate hardware exists.   * Setup porterboxen for Debian package maintainers to login to and port packages.
Line 73: Line 73:
Improve the port until it satisfies the [[https://release.debian.org/testing/arch_policy.html|criteria for being included in a Debian release]].   * Optionally, donate hardware for [[debci]]. It is recommended to do this so Debian package maintainers have a way to automatically run as-installed package tests.
Line 75: Line 75:
Make the port more performant by porting or optimising various libraries (ToDo: add examples).   * Optionally, donate hardware for [[Teams/SalsaCI]]. It is recommended to do this so Debian package maintainers have a way to automatically build and test changes to packages before upload.
Line 77: Line 77:
Make the bootstrap process more trustworthy through [[https://bootstrappable.org/|Bootstrappable Builds]].   * Optionally, donate hardware for [[https://debomatic.github.io/|debomatic]]. It is recommended to do this so Debian package maintainers have a way to automatically trigger custom package builds.

  * Port the [[https://www.debian.org/devel/debian-installer/|Debian installer]] so that it works on the hardware you have available.

  * Use the Debian installer to install Debian on the hardware you have available.

  * Write some [[https://wiki.debian.org/InstallingDebianOn|documentation about installing the arch on the hardware]] you have installed.

  * Submit [[https://www.debian.org/releases/stable/amd64/ch05s04#submit-bug|installation reports]] for the hardware you have installed.

  * Submit some [[https://wiki.debian.org/Hardware/Database|hardware probes]] for the hardware you have installed.

= Official port =

  * Grow the hardware ecosystem until it satisfies the [[https://dsa.debian.org/ports/hardware-requirements/|requirements for an official port]].

  * Improve the port until it satisfies the [[https://ftp-master.debian.org/archive-criteria.html|criteria for being included in the main archive]].

  * Donate hardware for the official buildds and co-ordinate with [[Teams/DSA|the Debian sysadmins]] to setup the hardware in Debian hosting locations.

  * Add quality assurance for the port for [[https://reproducible-builds.org/|Reproducible Builds]], [[https://ci.debian.net/doc/|Debian CI]], and [[https://piuparts.debian.org/|piuparts]] (doesn't yet support non-x86 ports) and other [[qa.debian.org|Debian QA efforts]].

  * Add support for the port to the [[https://www.debian.org/devel/debian-live/|live images]] and [[Cloud|cloud]] images if appropriate hardware exists.

= Released port =

  * Improve the port until it satisfies the [[https://release.debian.org/testing/arch_policy.html|criteria for being included in a Debian release]].

= Other work =

  * Improve the port based on reports from users and QA services.

  * Make the port more performant by porting or optimising various libraries, language runtimes and signal processing algorithms and cryptography libraries, for example: openssl, gnutls, openjdk, v8, ffmpeg, golang, gccgo, ghc, ocaml

  * Make the bootstrap process more trustworthy through [[https://bootstrappable.org/|Bootstrappable Builds]].

This is an aspirational document describing the most ideal procedure for creating a new port and getting it included into Debian. Since every port will have different circumstances, the procedure may differ for your port, but the best way to do it should be documented below. It is a work in progress and is based on the port template wiki page.

/!\ It is best to not skip any of the steps.

/!\ It is best to complete each item before moving to later steps.

Preparation

  • Assemble a team of people working on the port and find a financial sponsor to support the team's work.

Upstreaming

  • Decide on the architecture ABI details and the GNU triplet. A different GNU triplet is required for each ABI, which includes bitness, endianness, soft/hard-float, calling convention, or whether object files can be inter-linked.

  • Register accounts for each team member on the bug trackers and subscribe to the mailing lists for upstream projects: GNU config, binutils, gcc, gdb, qemu, kernel (such as Linux), and libc (such as glibc)

  • Prepare kernel and toolchain patches supporting the port and get the necessary changes included into these upstream projects: GNU config (instructions), binutils, gcc (instructions), gdb (instructions), the kernel (such as Linux (info)) and the libc (such as glibc (instructions)) (in that order)

  • If hardware supporting your port is not yet available or your hardware or FPGA softcore or software model is quite slow, prepare patches for the appropriate simulator/emulator upstream project (such as qemu (instructions)). If you do not need this, it will still be very useful to complete at some point, so consider completing it later on.

Downstreaming

  • Identify related ports and ISAs, decide that the port is worth creating and detail the reasons why.
  • Register accounts for each team member on the Debian wiki (registration) and Salsa (register).

  • Register and verify accounts for each team member on the OFTC IRC chat network and join the #debian-bootstrap, #debian-ports and other Debian IRC channels.

  • Discuss the port with the community. Please send an email to the debian-devel mailing list. If the port is related to some other architectures, ensure you CC the mailing list for the architecture family. Also join the #debian-bootstrap and #debian-ports IRC channels.

  • Finalise the architecture details, especially including the ABI and CPU baseline requirements.
  • Get any necessary changes included into dpkg (instructions), to get the new Debian architecture name supported (which is the name that end-users will use for the architecture), this requires having the architecture ABI details clear, the Debian multiarch tuple is derived from the Debian architecture tuple.

Bootstrap

  • Prepare patches supporting the port in rebootstrap and other Debian-specific packages.

  • Use your modified rebootstrap, the other patches and manual bootstrapping to build all of build-essential.

  • Keep working on the bootstrap process until all of build-essential is installable with debootstrap.
  • Continue building as many packages as you can using the new build-essential packages.
  • Get any remaining changes included into the upstream projects that you have modified.
  • Get any necessary changes included into rebootstrap and other projects involved in the bootstrap process.

Unofficial port

  • Register the port on the Debian wiki, replace "example" throughout the page with the chosen architecture details and fill out as many details as you have.

  • Summarise the details of the architecture and ABI on the arch summary wiki page.

  • Setup communication channels for the architecture. Use the architecture family as the name of any communication channels you create, just in case additional related architectures are created later. A mailing list and IRC channel are recommended.

  • Add your architecture to the bugs arch usertags page.

  • Get the port included amongst the unofficial ports.

  • Setup unofficial buildd servers for the port, either in qemu or hardware.

  • Include the port on the ports list on the Debian website and add the end-user name for the port to the website arches data. If you create a page on the website, create one named after the architecture family, just in case additional related architectures are created later.

  • Monitor build failures (1 2) and continually fix issues.

  • Optionally, donate hardware for the GCC compile farm. It is recommended to do this so that people outside Debian also have access to hardware for testing toolchains or other software on your port.

  • Setup porterboxen for Debian package maintainers to login to and port packages.
  • Optionally, donate hardware for debci. It is recommended to do this so Debian package maintainers have a way to automatically run as-installed package tests.

  • Optionally, donate hardware for Teams/SalsaCI. It is recommended to do this so Debian package maintainers have a way to automatically build and test changes to packages before upload.

  • Optionally, donate hardware for debomatic. It is recommended to do this so Debian package maintainers have a way to automatically trigger custom package builds.

  • Port the Debian installer so that it works on the hardware you have available.

  • Use the Debian installer to install Debian on the hardware you have available.
  • Write some documentation about installing the arch on the hardware you have installed.

  • Submit installation reports for the hardware you have installed.

  • Submit some hardware probes for the hardware you have installed.

Official port

Released port

Other work

  • Improve the port based on reports from users and QA services.
  • Make the port more performant by porting or optimising various libraries, language runtimes and signal processing algorithms and cryptography libraries, for example: openssl, gnutls, openjdk, v8, ffmpeg, golang, gccgo, ghc, ocaml
  • Make the bootstrap process more trustworthy through Bootstrappable Builds.