Development

Welcome to Funtoo, new developers!

   Warning

This page is a work in progress as of 05/09/2020 and it's content may change until this is marked as "finished"

Prologue

This wiki page will guide you on how to create and maintain proper funtoo ebuilds, for both common Funtoo users and developers.

One thing that makes Funtoo unique among other Linux distributions is the fact that it allows it's users to squeeze every ounce of power in their computers, making it one of the fastest distributions available to download nowadays.

Even though Funtoo comes with a ton of available software in its repositories there will be some cases where you need a special piece of software that isn't available or maybe it's outdated.

Maybe you wondered "How do Funtoo developer make those awesome ebuilds?" you might think it's something difficult to do. Truth be told, if you are a newcomer to Funtoo it might be. However, if you have some experience this will be a FUN experience for you, you may need some shell programming experience but you don't need to be a master to actually know what is going on.

A few things to have in mind

Since you want to become a Funtoo maintainer, first you'll need to know some rules and tips before you get started.

Maintaining software in Funtoo is a great responsibility, building, debugging and updating packages can sometimes be time-consuming.

For Funtoo it is important that it's users get well tested, quality software and sometimes new software isn't required. However, don't get put off by this, you can help maintaining packages that have been orphaned or help other Funtoo devs autogen packages that excel at their latest versions.

What is fine and what is not

Funtoo is a community distribution and you have to collaborate with that community if you want your package to be included, so let us give you some tips on what you should or shouldn't do when maintaining software in Funtoo.

It is OK to:

• File a bug requesting a package and opening a PR to add that specific package.

• File a bug requesting a package version bump using a correct rationale and PR the specific version bump.

• Open a PR bringing software (that works!) from other distributions.

• File a bug or open a PR asking to be the new maintainer of an orphaned package.

It is NOT OK to:

• Open a PR to add your own arbitrary software. (Don't take this personally, but before doing that think of the following questions: Does it solve a Funtoo problem? Is anyone in the Funtoo Community getting a benefit from this?, Is this REALLY needed in Funtoo?)

• Package a new piece of software and dissapear, leaving it unmaintained.

• Package malicious, tampered or infected software (We will know!)

• Spam the Funtoo JIRA or Bitbucket with comments just to hurry a PR, please mind that the Funtoo devs are human beings like you and they might not be available 24/7.

• Plain copy-pasting ebuilds! Please avoid this as much as possible, we know it might save you work but doing that will make things more difficult for you to debug.

Now that we got some of those points covered let's get our hands dirty with some good ol' Funtoo work.

Funtoo Developer Tookit

Before you start working you'll need some tools first, for basic ebuild creation this should suffice but bear in mind that you may need more advanced tools the bigger your ebuild pretends to be.

Required tools for Funtoo Packaging:

• A Funtoo Installation.
• A text editor of your choice (Just avoid using ed, for pete's sake).
• Your favorite Terminal emulator.
• automake, autoconf, meson or whatever build system your software needs for building and installing.
• git (For JIRA + BitBucket usage)
• A backup if you are testing your ebuilds in bare metal (Trust us, you'll need one)

   Note

Please try documenting yourself about your package dependencies and build system as it can turn complex if you leave those requirements behind when testing your ebuild

Help! I got stuck at...!

Don't worry, we all make mistakes sometimes, if you run into any problem following this guide please reffer to the https://discord.com/invite/BNUSpUUand feel free to ask any questions you may have.

First steps

Since Funtoo is a source-based distribution most of it's software must be build from sources. Usually the Funtoo software adding process is the following:

1. Choose your desired program to package or maintain.
2. Clone the respective Kit git repository your ebuild belongs to.
3. Create a directory with the name of the program you wish to package.
4. Create a .ebuild file named: program-version.ebuild
5. Code your ebuild :)
6. Digest your ebuild running ebuild digest <.ebuild-file>
7. Open a Pull Request in code.funtoo.org with a proper rationale.
8. Wait some time.
9. Enjoy new software ready to use.

In this guide we will cover these points, from choosing to packaging software for other Funtoo users to enjoy.