Gentoo Developer HandbookContent:
A. Introduction1. IntroductionThe aim of this handbook is to outline Gentoo development policies, and make you, the developer, informed of policies, standards and procedures which Gentoo considers to be core values of our development system. This handbook is not intended to be the universal guide to everything - the opportunities open to you are endless, and as a result, this handbook is designed to teach you the principles which we think make up a good Gentoo developer - the rest is up to you! If you are new to Gentoo development or even an old veteran and are at any stage unsure about anything, feel free to ask the gentoo-dev mailing list, or #gentoo-dev. Before you start to tinker, it is important to have a working Gentoo installation, both for documentation and development purposes, and we also recommend that you have a good knowledge of topics covered in the ``Working with Gentoo'' section in the User Handbook to help you with your development work. Most of this guide is targeted at developers, but, if you are just interested to see what makes Gentoo development work, this guide may provide some valuable insights. The best way to get noticed [ and to possibly become a Gentoo developer! ] is to file intuitive and accurate bug reports at the Gentoo Bugzilla, with patches if possible, and to help us out with what you think would make a better Gentoo for everyone whether by providing patches for new features, submitting new ebuilds, or solving issues with existing ones. 2. Becoming a developerThere are many ways to become a Gentoo developer, which this section discusses. There are also various steps that new "recruits" have to go through before they become official developers. Firstly; to be asked to become a developer you should either apply to an opening, or just help out whether in the form of user support or filing bug reports - we notice frequent contributors making contributions to Gentoo and we attempt to reward them by giving them the chance to become a Gentoo developer. Gentoo has many paths, and the Gentoo Developer Relations Recruitment Team is always looking out not just for developers - documentation writers and infrastructure maintainers are just as important too for our distribution to run smoothly. You should look out for openings for developers in the GMN, as well as the /topic of #gentoo-bugs on irc.freenode.net - if you feel you could fill in one of those positions, try to find a mentor who is willing to sponsor you, or contact the Gentoo Recruiters who may be able to find a mentor for you. Please do not file "New Developer" bugs on yourself since this task is designated for the mentor and any such bugs will be closed. All new developers must have a mentor, who is an existing Gentoo developer responsible for guiding a new developer as well as offering to help the developer later after the developer has passed through the recruitment process. A mentor should assist you by helping you with any questions you might have, as well as outlining your Gentoo responsibilities, especially those in relation to what you would initially work on. Once a developer agrees to mentor a new developer, the mentor should file a bug and assign it to the Gentoo Recruiters - the Gentoo Recruiters page explains in detail what information should be filed.
All new developers pass through a waiting period of up to a month, depending on how ready the mentor thinks the developer is as well as feedback from any other related staff. During this time, the new developer should complete the quiz which would be reviewed by the developer's mentor and the Gentoo Recruiters to ensure that the developer is "ready". In special cases, the waiting period is determined by the Recruiters and/or Gentoo Developer Relations leads. Two quizzes are offered: the ebuild quiz, and the staff quiz. Developers who will be working purely on infrastructure, GLSAs or other non-ebuild areas should take the staff quiz, any developers who require commit access to the Portage tree should take the ebuild quiz. Once a new developer has completed the quiz, the developer should send it off to the mentor who is responsible for reviewing it in conjunction with the Gentoo Recruiters. If the quiz answers are deemed to be of a sufficient standard, then the recruitment process would continue. Otherwise, a new developer can redo the quiz again, providing that it is completed in the waiting period. Additionally, new developers should be responsive to any members of the Recruiters Team who have any questions - any developers who do not reply promptly will have their "New Developer" bug closed, which would only be reopened at the discretion of the Gentoo Recruiters. After your mentor and the Gentoo Recruiters have reviewed your quiz and deemed it to be of a suitable standard, you should send it along with a public SSH2 DSA key (e.g. id_dsa.pub) to the Gentoo Recruiters. If the Recruiters consider your quiz to be of a satisfactory standard, they will set you up with the services that you require. After this time, you enter a "probationary period" of 30 days during which your mentor is responsible for your actions, providing accountability - also, Gentoo Recruiters may reject new developers during this time if they feel it is appropriate. 3. What you getGentoo provides developers with all the necessary services which they might need for their development efforts. If you require anything else, please do not hesitate to contact the Infrastructure Team! Once you are an authorized developer, your recruiter should organize the following services. If you experience any problems, please see your recruiter or the mentioned staff with access to the required service. Developers are able to change all aspects of bugs in Bugzilla. If you have an existing account the email address should be changed to your Gentoo address by a Bugzilla administrator. Not all developers receive CVS access - if you require Portage access to the gentoo, gentoo-projects, or gentoo-x86 tree get someone on the recruiters team to do this for you. You may need to justify your need for this to happen, however. When you are a developer, you will receive operator status on #gentoo-dev signifying that you are a developer. Please contact Developer Relations if you do not. Additionally, team leads may decide to give you operator status on specialized channels such as #gentoo-hardened, for example. Abuse of operator powers on #gentoo-dev may lead to your operator powers being removed instantly along with the possible removal of your developership. If you are given operator powers, we ask that you use them constructively to benefit everybody when either developers or users break up the cleanliness of the channels. Operator status on #gentoo is given at discretion by Developer Relations; it does not in any way signify that the user is a developer. "Special" Gentoo channels such as #gentoo-hardened and #gentoo-server are given to people at the discretion of the team - in this case, the hardened and server teams. IRC Channels are owned by their relevant project leads, whether strategical or operational and the owner has the discretion of voicing or unvoicing members of the public. If you believe that those powers are being abused or are being used with wrong considerations; then speak to the Gentoo Linux Developer Relations team. Ask one of the forums administrators in #gentoo-forums or forum-mods@gentoo.org to update your forum status on the Gentoo Forums, if needed. Forum accounts are not mandatory. Developers who have a personal blog can request to be added to the planet aggregator. The planet software creates a custom feed of all developer's blog posts, separated into two categories: on-topic (Gentoo and computer related content) on Planet Gentoo, and all topics on Gentoo Universe. Also, if a user does not already have a blog, we host our own blogging software and can create an account for you. Please see http://www.gentoo.org/proj/en/userrel/planet/index.xml for more details. All developers are provided with a developer@gentoo.org mail address for Gentoo use. Please see http://www.gentoo.org/proj/en/infrastructure/dev-email.xml for more details. All developers must be subscribed to the gentoo-core and gentoo-dev-announce mailing lists. All developers should be subscribed to gentoo-dev and gentoo-project, though neither are developer requirements. Contact someone on the Recruiters team to subscribe you to the above mailing lists or if you are having difficulties. gentoo-core is to be used for internal discussions; technical discussions should be discussed on gentoo-dev; off topic or non-technical discussions should be discussed on gentoo-project; while gentoo-dev-announce is for announcements only. If you send a message to dev-announce, and expect a discussion to take place relating to it, you should manually cross-post and set reply-to suitably. If you are subscribed on any other Gentoo mailing lists, you should unsubscribe and resubscribe with your new mail address. Developers currently get a shell account on dev.gentoo.org - this provides mail storage, SMTP relaying and also an IRC tunnel for developers to use to access freenode. To ensure security, access is only available through SSH keys, which your mentor should place on your account and allow you to log in: please see http://www.gentoo.org/proj/en/infrastructure/cvs-sshkeys.xml for more details regarding SSH keys.. Services provided by Gentoo should only be used for Gentoo development work. Infrastructure has the right to disable any accounts which are a security risk, these include inactive accounts which will be suspended by the infrastructure team if you are presumed idle, and your IRC #gentoo-dev status would also be voiced. If any files in your account are found to be harmful towards other developers or users on the box, or pose a risk to the Gentoo project (such as illegal .torrents), Gentoo Infrastructure will suspend your account which would only be unlocked after investigation from Gentoo Developer Relations. In most cases, your developership may be suspended if such files are found. The same policies also apply to Gentoo CVS and other Gentoo-provided services you may be offered. Gentoo understands that as life changes, so may your availability. We respectfully request that if you know you will be unavailable for an extended period of time (vacation, big project at work, family needs, etc) that you utilize the devaway system.
In the on going effort to keep our developer pool up-to-date and our resources secure, Developer Relations periodically reviews developer activity in the search for inactive developers. A developer is considered inactive if no contributions are made over a period of 60 days. Activity is determined by CVS commits, bugzilla statistics, and peer feedback. Not everyone's activities are so easily traced, as such, Developer Relations often requests feedback from a project lead or team members of a developer suspected to be inactive. Any developer suspected to be inactive for a period in excess of 60 days may be subject to retirement. Developer Relations will first research and assess the situation, attempt to contact the developer, or if attempts are unsuccessful may chose to retire the developer. Please note that if you are in devaway for more than 60 days, you may also be considered inactive, however, return dates will be taken into consideration. If you are retired due to inactivity and wish to return, you need only contact Recruiters to begin the recruitment process again. 4. Help for new developersThis guide is not intended to be a manual on using CVS; for that, take a look at the CVS info page or /doc/en/cvs-tutorial.xml. Instead, this guide focuses specifically on using CVS and Repoman in Gentoo's ebuild tree. Typically, you'll want something along these lines in your ~/.cvsrc:
Finally, many people using CVS like to use compression (-z#). We ask that developers who are not on dialup connections please use -z0 - with the contents of our CVS repository and the load on our CVS server, you actually experience a speed increase without compression. There are a few useful modules in Gentoo's CVS repository. Ebuilds are kept in the gentoo-x86 module. gentoo contains the XML for the website, documentation, developer directories, developer pictures, and so on. gentoo-projects contains various projects and generally replaces the gentoo-src cvs module. gentoo-src is kept around for history, please transition to a different cvs module if you are still using it.
Before working in the tree at any time, it's always a good idea to do an update to check for changes and prevent conflicts. You can update in any subdirectory of the tree if you don't want to wait for a tree-wide update, but from time to time it's a good idea to update your entire tree:
Gentoo also offers subversion services for those who prefer SVN over CVS. Many core projects such as portage and baselayout are hosted here now.
If you want to use CVS as your primary Portage tree, you can add the following lines to /etc/make.conf, replacing you with your username:
On supported architectures, you should also have sandbox in your FEATURES to ensure ebuilds do not modify the root filesystem directly. Say you're ready to add a brand new package, foo, in app-misc:
See the Gentoo Metadata section for more information on metadata.xml. At this point, you're ready to commit (see the section on Commits below). But what if you want to remove foo-1.0 when foo-1.1 is out?
And now you're ready to commit (see the section on Commits below). Always use repoman commit rather than cvs commit. Repoman is a quality assurance (QA) tool that performs basic checks and creates Manifests. If any part of repoman's output is unclear, please see man repoman. Additionally, you may tire of entering your key passphrase repeatedly; keychain (http://www.gentoo.org/proj/en/keychain.xml) can help you.
If you have noticable high ping times to the cvs server, you might want to use the ssh master slave setup where you only connect to the other ssh server once and let it do the next commands over that connection. This way you save the handshake overhead which may speed up the whole checkout/commit by factor 3. Just add the code snipped given below to your config
After doing so, you can enable a backgrounded master connection by running
Distfiles are automatically fetched by the Gentoo Mirror System. You only need to monitor your distfiles for fetch errors. Please see the Distfiles Overview Guide for comprehensive instructions. Our infrastructure allows developers to manage their own mail. http://www.gentoo.org/proj/en/infrastructure/dev-email.xml contains instructions on configuring your @gentoo.org mail. Developers have access to webhosting, http://dev.gentoo.org/~$YOURNAME. Please see the Webspace Configuration Guide for details. 5. Developer hierarchyThis section aims to explain the Gentoo development hierarchy and gives developers an insight to how Gentoo Linux development management is structured. 5.b. A short history of Gentoo's management structure The first attempt to come up with a management structure to solve problems with coordination and communication issues was made in 2003 with the structure described in GLEP 4. As Gentoo grew larger over the time, some problems with the management structure were discovered and a new one was needed to solve these issues. GLEP 39 describes both the reasons behind this as well as the outcome of the discussion. 5.c. Current Management structure according to GLEP 39 A project is a group of developers working towards a goal (or a set of goals).
Global issues will be decided by an elected Gentoo council.
5.d. Consequences of Gentoo's management structure As a consequence of the new management structure, global decisions will be made by the elected council. This should give Gentoo a general direction - smaller issues affecting only a project or two should be decided inside the projects involved, probably with input from other developers. The council should be a fair representation of the developer base as every developer is able to vote, so interests should be represented in a fair way. If the council does a bad job and the developer base is unhappy with its work, the council can be voted out. Decisions within a project can be made by the people inside the project itself, of course coordination between the projects is necessary. The (sub-)project leads are usually responsible for doing this. Most projects have an Operational and Strategic lead, but basically it is up to the project what positions are created and how they are called - this also applies to sub-projects. Some projects appoint a contact person for communication to another project e.g. a developer within the forums project who is responsible for communication with the infrastracture project. All in all, the current structure has no clear list of responsibilities the project leads are supposed to satisfy. They are chosen by the members of the project, the practical responsibility of a lead is "whatever the members require", and if that isn't satisfied, the members can get a new lead (if they can find somebody to take the job!). 6. Staff member policy6.a. Gentoo Staff Member policy Running a Linux distribution has multiple aspects and many of them aren't directly connected to coding. Every distribution needs people to run its servers, help its community, provide documentation, handle project's finances and legal issues and serve many other tasks. Their contributions are as important as code contributions. These developers are called staff members in Gentoo. The following list contains all types of staff members we are currently recruiting in Gentoo:
How is staff member access different from ebuild developer access? Access is assigned based on the responsibilities of the Staff Member. All Gentoo Developers are provided with an gentoo.org mail address, ssh access to dev.gentoo.org (for shell, ldap, public_html, etc) as well as cvs access to gentoo's web/project pages. As a staff member you will not be granted access to the ebuild tree, as ebuild developers are, but may be granted access to other area's based on your need and responsibilities. How can I become a Gentoo staff member? You have to work with members of the project you wish to help. You are invited to the team when your level of contributions and expertise justify you becoming a developer in that project. It may take time and may also require passing internal recruitment procedures within that project first. Those procedures are in place to ensure you know what your future function within Gentoo involves, they are created and maintained by the project itself. When you are ready, you will need to look for a mentor and a developer bug will be filed for you after your mentor has approved your staff quiz. Once a recruiter has been assigned to your developer bug, both of you will need to schedule your review. Please see the mentoring guide for more information.
I would like to be recruited as a staff member but also plan joining other projects in future Every Gentoo developer can join any project (s)he wishes if developers of the project agree with that. Before you can start contributing to the ebuild tree though, you will have to apply for ebuild developer recruitment. This means you need a mentor, a history of technical contributions (bug fixes, overlays, etc...) and adequate training. Please contact recruiters about this. How is retirement handled for staff members? You have to either remain active within the project you have joined or move to other projects. If there are no projects within Gentoo you're active in, you are subject for retirement via Gentoo Undertakers procedures. B. Guides1. Ebuild HOWTOThe Portage tree is typically found at /usr/portage and is organized in a hierarchical structure consisting of category directories, followed by specific package directories. Here's an example; you can find the util-linux-2.11y.ebuild file in the /usr/portage/sys-apps/util-linux directory. There may be several other versions of util-linux ebuilds alongside util-linux-2.11y.ebuild. This is because all ebuilds for a particular package (regardless of version), share the same mycat/mypkg directory in /usr/portage, unless you have portage overlays installed. Checking Out the Portage Tree from CVS If you are unfamiliar with the CVS system, please read the CVS Tutorial for more information. The Portage tree can be found in the gentoo-x86 module of the Gentoo Linux tree. To check out the module (about 350 megabytes) you would first set up CVS via the above guide, then check out the gentoo-x86 module. What (not) to put in the Portage tree Before writing a new ebuild, check bugs.gentoo.org to see if an ebuild has already been written for the package, but has not yet been added to the Portage tree. Go to bugs.gentoo.org, choose query and select Advanced Search; as product select Gentoo Linux, as component select ebuilds. In the search field put the name of the ebuild and as status select NEW, ASSIGNED, REOPENED and RESOLVED (RESOLVED is important), then submit the query. For you lazy people, click here. In general, the Portage tree should only be used for storing .ebuild files, as well as any relatively small companion files, such as patches or sample configuration files. These types of files should be placed in the /usr/portage/mycat/mypkg/files directory to keep the main mycat/mypkg directory uncluttered. Exceptions to this rule are for larger patch files (we recommend this for patches above 20KB) which should be put onto the Gentoo mirrors so that people do not waste excessive amounts of bandwidth and hard drive space. Also, you should not add binary (non-ASCII) files to the Portage CVS tree. If you need to do this in another CVS tree, for example, if you need to add a small PNG graphic for whatever reason, be sure to add it to CVS by using the -kb option, like so:
The -kb option tells CVS that myphoto.png is a binary file and should be treated specially. For example, merging the differences between two different versions of this file should not be allowed to happen, for obvious reasons. Also, speaking of merging changes, any patches you add to Portage should generally not be compressed. This will allow CVS to merge changes and correctly inform developers of conflicts. Remember, the packages that you commit must be ready out of the box for end users when committed as stable. Make sure that you have a good set of default settings that will satisfy the majority of systems and users that will use your package. If your package is broken, and you are not sure how to get it to work, check some other distributions that have done their own versions of the package. You can check Mandriva or Debian or Fedora for some examples. When committing to CVS, all developers should use repoman commit instead of cvs commit to submit their ebuilds. Before committing, please run repoman full to make sure you didn't forget something.
As noted earlier, under each package subdirectory is a files/ directory. Any patches, configuration files, or other ancillary files your package might require should be added to this directory; any files bigger than 20KB-or-so should go to the mirrors to lower the amount of (unneeded) files our users have to download. You may want to consider naming patches you create yourself just to get your package to build with a version-specific name, such as mypkg-1.0-gentoo.diff, or more simply, 1.0-gentoo.diff. Also note that the gentoo extension informs people that this patch was created by us, the Gentoo Linux developers, rather than having been grabbed from a mailing list or somewhere else. Again, you should not compress these patches because CVS does not play well with binary files. Consider prefixing or suffixing (such as mypkg-1.0) every file you put into the files/ directory, so that the files used for each individual version on an ebuild are distinguishable from one another, and so that the changes between different revisions are visible. This is generally a really good idea :). You may want to use a different suffix if you wish to convey more meaning with the patch name. If you have many files that should go into the files/ directory, consider creating subdirectories such as files/1.0/ and putting the relevant files in the appropriate subdirectory. If you use this method, you do not need to add version information to the names of the files, which is often more convenient. Ebuild scripts are the basis for the entire portage system. They contain all the information required to download, unpack, compile and install a set of sources, as well as how to perform any optional pre/post install/removal or configuration steps. While most of Portage is written in Python, the ebuild scripts themselves are written in bash, since using bash allows us to call commands as we would from the command-line. One of the important design principles behind ebuild scripts is to have the commands therein be analogs of those one would type on the command-line if installing the package manually. For this purpose, using bash syntax is a very good thing. Ebuild scripts are interpreted by the ebuild and emerge commands. Think of the ebuild command as a low-level building tool. It can build and install a single ebuild, but no more. It will check to see if dependencies are satisfied, but it will not attempt to auto-resolve them. On the other hand emerge is a high level engine for ebuild, and has the ability to auto-merge dependencies if needed, perform pretend merges so that user can see what ebuilds would be merged, and more. Generally, emerge blows ebuild out of the water except in one area. With ebuild, you can incrementally step through the various parts of a package emerge (fetching, unpacking, compiling, installing and merging) one at a time. For developers, this is an invaluable debugging tool, because it allows you to isolate ebuild problems to a specific portion of the ebuild. Ebuild file names consist of four logical subsections: pkg-ver{_suf{#}}{-r#}.ebuild
The first subsection, pkg, is the package name, which should only contain lowercase letters, the digits 0-9, and any number of single hyphen (-), underscore (_) or plus (+) characters. Examples: util-linux, sysklogd and gtk+. We have some packages in Portage that don't follow these rules, but your packages should. The second subsection, ver, is the version of the package, which should normally be same as the version on the main source tarball. The version is normally made up of two or three (or more) numbers separated by periods, such as 1.2 or 4.5.2, and may have a single letter immediately following the last digit; e.g., 1.4b or 2.6h. The package version is joined to the package name with a hyphen. For example: foo-1.0, bar-2.4.6.
The third subsection, {_suf{#}}, is optional and may contain one of these predefined suffixes, listed in least-recent to most-recent order:
Any of these suffixes may be immediately followed by a non-zero positive integer, e.g., linux-2.4.0_pre10. Assuming identical version parts, the suffixes are ordered as follows (lower means older): _alpha < _beta < _pre < _rc < (no suffix) < _p. When comparing identical suffixes with trailing integers, the one with the larger integer will be considered most recent. Example: foo-1.0_alpha4 is more recent than foo-1.0_alpha3. The fourth subsection of the package name is the Gentoo Linux-specific revision number ({-r#}). This subsection, like the suffix, is also optional. # is a non-zero positive integer; e.g., package-4.5.3-r3. This revision number is independent of the version of the source tarball and is used to inform people that a new and improved Gentoo Linux revision of a particular package is available. Initial releases of ebuilds must have no revision number; e.g., package-4.5.3 and are considered by Portage to have a revision number of zero. This means that counting goes as follows: 1.0 (initial version), 1.0-r1, 1.0-r2, etc. If you make non-trivial improvements to an existing ebuild file, you should copy the ebuild file to a new file with the revision number incremented by 1. Remember to always make mentions of your changes in the ChangeLog when you bump a revision and in your CVS commit message; not doing so is against policy. ... and I suppose that we actually have a fifth section of the ebuild name as well -- the .ebuild extension itself. This section is an introduction to ebuilds. For the full listing of everything possible in an ebuild, there is a manpage which talks about the internal format, variables, and functions in an ebuild script: man 5 ebuild. Headers When you submit your ebuilds, the header should be exactly the same as the one in /usr/portage/header.txt. Most importantly, do not modify it in any way and make sure that the $Header: $ line is intact. The first three lines should look something like this:
Variables The first part of every ebuild file is made up of a number of variables. See the devmanual for information on the different variables. Functions There are a number of different functions that you can define in ebuild files that control the building and installation process of your package.
Helper Functions You can also use the following helper functions in your ebuilds.
Helper Functions provided by eutils.eclass You can use the following helper functions that are provided by the "eutils" eclass in your ebuilds. You must make sure that inherit eutils is present for these functions to work.
Helper Functions provided by flag-o-matic.eclass You can use the following helper functions that are provided by the "flag-o-matic" eclass in your ebuilds. You must make sure that inherit flag-o-matic is present for these functions to work. You should never modify any compiler settings directly, instead please use flag-o-matic to perform any actions such as filtering flags that cause trouble.
Helper Functions provided by toolchain-funcs.eclass You can use the following helper functions that are provided by the "toolchain-funcs" eclass in your ebuilds. You must make sure that inherit toolchain-funcs is present for these functions to work. You should never explicitly specify any compiler or binutils settings directly, instead please use toolchain-funcs to specify compilers and binutils. The purpose of using the below functions is to support cross-compiling and the icc compiler. These should be used whenever a package explicitly uses gcc, g++, ld, ranlib or any of the below tools. In general packages that use autoconfiguration tools detect cross compiling automatically and do not need the following functions.
Rules for writing an ebuild file Since ebuild files are really just shell scripts, you should use your editor's shell-script mode for editing them. You should use proper indentation, using only tab characters -- no spaces. Make sure you set up your editor to put tab stops at 4 spaces. Always make sure you use braces around your environment variables; e.g. ${P} instead of just $P. Long lines are wrapped with ' \', thus:
For further details, refer to skel.ebuild (usually residing in /usr/portage). If you use Vim for ebuild/eclass editing, the default Gentoo vimrc file, /etc/vim/vimrc, already ensures that correct indentation and filetype settings are used for ebuild and eclass files. For better results, including special syntax highlighting for ebuild keywords, emerge app-vim/gentoo-syntax. On non-Gentoo systems, you can obtain similar results by using the following lines in your vimrc, or better yet by installing the gentoo-syntax scripts which can be downloaded from Gentoo mirrors.
If you're using Emacs, you should emerge app-emacs/gentoo-syntax (for GNU Emacs) or app-xemacs/gentoo-syntax (for XEmacs). These packages provide Emacs major modes for automatic indentation and syntax highlighting of ebuilds and other Gentoo specific file types. If you're using nano, then you're in luck! Just edit /etc/nanorc and uncomment the section referring to ebuild's. The purpose of USE variables is to allow you to configure Portage to globally and automatically enable or disable certain optional build-time features. Here's an example. Let's say you're a GNOME fan, and you'd like any ebuild that has the option of compiling-in optional GNOME support to do so. In this case, you'd add gnome to the USE variable in /etc/make.conf, and then Portage will automatically add optional GNOME functionality to packages if it is available. Likewise, if you don't want optional GNOME features to be added to your ebuilds if they are available, simply edit /etc/make.conf and make sure that gnome is not set in the USE variable. Gentoo Linux has an almost overwhelming number of USE options, allowing you to have your system configured exactly the way you want it.
In your own ebuilds, you can check whether a USE variable is set by using the use <variable> command. You would normally use this command as follows:
USE variables can also be used to set dependencies. For example, you may only want to require a package if a certain USE variable is set. This is done by using the syntax flag? ( mycat/mypackage ) in the DEPEND variable for your ebuild. In this example, mycat/mypackage will only be required if flag is present in USE. It is also possible to specify what dependency should be used if some USE flag is set, and what dependency to use if it is not set: flag? ( mycat/mypackage) and !flag? ( othercat/otherpackage ). In this case, if flag is not set, othercat/otherpackage is used instead of mycat/mypackage. Make sure that your ebuilds use this syntax and not Bash if's. Bash conditionals interfere with Portage's dependency caching, and the use of them will break your ebuild. Here's an important tip about how to use USE. Most of the time, a package will have a ./configure script used to perform configuration steps. Generally, if your ebuild uses ./configure, any optional build-time functionality will be enabled or disabled by passing the appropriate arguments to the ./configure command. Here's the best way to handle this:
This approach has a very nice result. We don't have to worry about what the default setting is for mysql or X (enable/disabled), we explicitly tell econf what we want it to do based upon the USE variable. Not to mention it's quite clean in terms of readability :). Occasionally, ebuilds will have conflicting optional features. Checking for these conflicts and returning an error is not a viable solution. Instead, you must favor one of the features over the others. As to which, consult upstream (what they use as typical default), or consider which option provides more common functionality, or just flip a coin. One example comes from the msmtp ebuilds. The package can use either SSL with GnuTLS, SSL with OpenSSL, or no SSL at all. Because GnuTLS has a lot more features compared to OpenSSL, it is favoured:
To view a continuously updated table of USE variables, please go here. The file system layout standards used in Gentoo Linux closely follow the FHS, short for File system Hierarchy Standard. A simplified description of the standard is given here; for a complete specification go to http://www.pathname.com/fhs/.
How to fit your packages into the file system Usually, if the package uses autoconf and automake, the default installation destinations are mostly correct, with a few exceptions:
In general, you should have ebuilds install their files into the /usr tree. Some programs can be compiled and linked with or without GNOME, KDE, and X11 libraries, which can cause confusion. Our solution is to install everything into /usr which avoids ambiguity and needless complexity for ebuild authors. The location in which to install a program's files should not depend on the presence or absence of specific USE variables. Therefore, the ebuilds in the portage tree almost always install into the /usr hierarchy exclusively.
1.d. The Portage scripts and utilities These are scripts used by the system-administrator to install and remove packages, and maintain the package database. ebuild is the main engine of the Portage system; it performs all major tasks such as unpacking, compiling, installing, merging, and unmerging packages. It is called using the command: ebuild path/to/package.ebuild command. The commands available are:
emerge recursively merges a package and all of its dependencies into your file system. This command has many options, try emerge --help for a list of them. env-update updates the configuration files (including, but not limited to /etc/ld.so.conf and /etc/profile.env) to include changes made by installed packages. These are scripts you can use in your ebuild files to perform common tasks. For you down and dirty people, look at the scripts themselves in /usr/lib/portage/bin.
Why dependencies are important Portage is more than just a convenience script that gives you a unified way to build any one project (program, library) from source. It will also fetch and install any necessary dependencies if you take care to specify these in your ebuild. In the official ebuilds, all dependencies have already been specified, so when you issue emerge net-www/mozilla/mozilla-1.0, Portage will insure that all libraries necessary for Mozilla to build and run are properly installed before Mozilla itself is built. Portage even distinguishes between build-time dependencies and run-time dependencies. (Caveat: Currently, Portage installs all build-time and run-time dependencies and leaves it at that. At a later stage, it will be possible to trim your installation so that only the run-time dependencies are left installed). How to Specify Dependencies in Your ebuild Files (a.k.a. DEPEND Atoms) The DEPEND variable inside your foo-x.y.z.ebuild tells Portage about which packages are needed to build foo. The RDEPEND variable specifies which packages are needed for foo to run. RDEPEND should be set explicitly even if it's the same as DEPEND because in the future it defaulting to DEPEND is planned to be removed from Portage.
This tells Portage that to build foo-x.y.z, the packages virtual/opengl (more on virtuals in a bit) and dev-libs/libxml2 are needed. It does not say anything about which version of opengl or libxml2 that are needed, which means "anything goes". The "anything goes" is of course a bit scary, and will not work in the general case. But for libraries, which strive very hard to be 100% binary compatible all the time, it actually works. For other libraries, we can of course specify version dependencies.
>= and = do what you would expect; sys-apps/bar version 1.2 or newer is okay (this means that sys-apps/bar-2.0 is okay), while sys-apps/baz version 1.0 is the only version that is accepted. For more information on the version schema of packages, see the section above on Naming ebuild Files. Other methods of specifying version dependencies are as follows:
~sys-apps/qux-1.0 will select the newest portage revision of qux-1.0. =sys-apps/foo-1.2* will select the newest member of the 1.2 series, but will ignore 1.3 and later/earlier series. That is, foo-1.2.3 and foo-1.2.0 are both valid, while foo-1.3.3, foo-1.3.0, and foo-1.1.0 are not. Please note that foo-1.22.3 will also match, which can become a problem at times. !sys-libs/gdbm will prevent this package from being emerged while gdbm is already emerged. There are many things that go wrong with the DEPEND and RDEPEND variables. Here are some important points to follow when you write the dependencies.
Additionally, it is important to ensure that all the dependencies are complete for your package:
For all the latest details about these DEPEND Atoms, please see the section 5 manpage on ebuilds: man 5 ebuild. Whenever you update (or write a new) an ebuild, you must also update its (or create a new) ChangeLog. The skel.ChangeLog contains a sample ChangeLog that you can use as a basis. The purpose of the ChangeLog is to document what is being done, why it is being done, and by whom. This allows both developers and users to trace the changes made in an easy way. The ChangeLog is primarily targeted at users, so be sure to keep your writing short, to the point, and avoid getting verbose about the internal technical details. Storing your own ebuilds locally In order to be able to test your ebuilds and let Portage know about them, you must place those in a known directory. Portage will use the PORTDIR_OVERLAY variable which you can define in /etc/make.conf. You should set this variable to your directory (e.g. /usr/local/portage). In that directory, you must use the same structure (and categories) as in /usr/portage. Using this PORTDIR_OVERLAY, your ebuilds remain on your system, even after an emerge sync, and they are still known to Portage. Have a think about how you will test whether this package works. Sometimes the developers have already included a make test or make check routine that will test the basic functionality of the package. If so, then running FEATURES=test ebuild foo-x.y.z.ebuild test will execute it. If it is broken try to fix it so that it works (and submit the patch to the upstream developers). If this is not the case consider adding a src_test routine to your ebuild. This is executed before the src_install routine and can be very helpful for testing the program works across various architectures. The architecture developers will appreciate if you add a routine here so that they do not require knowledge of the package's functionality. Please keep in mind the general requirements of an ebuild here. The src_test routine must not be interactive. If the test routine depends on other packages use the test USE flag to specify the optional compile time DEPENDancies. Also, please note that src_test routines are not recommended for graphical X applications as the user running portage often cannot run them successfully. We have a few useful tools to help you with writing and maintaining your ebuilds.
2. Eclass HOWTOeclasses are modules of shared code. They are written in bash and have the same syntax as ordinary ebuilds, and are sourced ('inherited') by ebuilds and other eclasses, to provide default settings and functionality across many similar ebuilds. This is used to ensure maximum code reuse among similar ebuilds. This first chapter shows briefly how to write an eclass incorporating the standard tricks and techniques used in existing eclasses. The second is an overview of the kde eclasses.The third explains how to write a KDE ebuild using the kde group of eclasses. Here is a fictive sourceforge.eclass, designed to provide homepage and download locations to sourceforge.net-hosted projects:
The first four lines are headers, just like those in any ebuild. The next two lines are a short description of the eclass. The rest of the code does the actual work - setting SRC_URI and HOMEPAGE. Most eclasses go beyond setting variables and providing helper functions; they contain default versions of the special ebuild functions (src_unpack, src_compile and so on). Before writing a default function in an eclass, you should be aware of the default functions already contained in ebuild.sh. They are what gets executed if you don't put some function in your ebuild (not even via an eclass); the default src_unpack() is often used. If you haven't yet, go and look at the default implementations in ebuild.sh. This is all you need to know to actually write eclasses. Put your new eclass in ${PORTDIR}/eclass/, and put this line at the beginning of your ebuild:
The contents of the eclass will be sourced at this point. Remember that any variables or functions defined in the eclass can be overridden in the ebuild, whose code executes after any eclasses. Therefore, you should try to put as much default settings and common code in your eclass as possible. Any nonstandard settings and modifications can then be put into the ebuild. Oh, and you can inherit several eclasses at the same time by saying:
...but watch their order! Remember, eclasses can inherit one another and override each other's settings, so you should be careful when dealing with multiple eclasses that might influence one another. We will now go over all the tricks of eclass writing, before moving on to the actual eclasses in portage. This function lives in ebuild.sh and handles inheriting (sourcing) of eclasses. It is called with a list of eclass names to inherit: inherit <eclass1> [eclass2 eclass3...]. Besides actually sourcing the eclass files, it sets the ECLASS and INHERITED variables which are used by portage for caching eclass modification timestamps. The INHERITED variable might be of use in writing eclasses: it contains a list of all eclasses inherited (sourced) up to this point, in order. Thus an eclass can use it to determine whether or not it was called from some other eclass. A good eclass's predefined functions can often be used as-is; the ebuild will then contain very little code (which is good). Sometimes, though, the eclass functions won't do exactly what you need. You could write a new function in your ebuild, overriding the function definition from the eclass. However, this would minimize the benefit of code reuse. So we try to 'extend' the eclass functions instead. Suppose you want to extend src_compile(). You can write an src_compile() definition in your ebuild, which would only include the parts missing from the eclass src_compile(). You would then call the eclass src_compile() from within the code of your custom function. However, if you create a new function called src_compile(), bash will forget about the old one and you won't be able to call it! That's where the EXPORT_FUNCTIONS macro comes into play. Let's look at another problem for a moment. Suppose that foo.eclass and bar.eclass both define src_compile(). If you inherit both foo and bar you'll get a different src_compile() depending on the order in which you inherit them. That's ok; you're supposed to keep track of your inheritance order. But you may want to call either of the two src_compile()s explicitly. So, every eclass adds to the functions that it defines a prefix. For example, foo.eclass will define a function called foo_src_compile(), and bar.eclass will define a bar_src_compile(). That way, the ebuild can call either function and know what it'll get. However, we also want to have some default function called just src_compile(), or the ebuild will have to define one. The EXPORT_FUCTIONS macro solves both this problem and the one presented earlier.
The inherit() function sets ${ECLASS} to the eclass's name before sourcing it. The eclass, at its end, calls EXPORT_FUNCTIONS(), passing as parameters the list of default functions it provides. For example, if you call
then EXPORT_FUNCTIONS will call eval() on the following string:
Now, whichever eclass is inherited last will define the default src_compile() function, but both functions can be directly called by the ebuild if needed. You can also extend the default src_compile() function by calling the eclass's function from within your own function. You then have to use the default function's full name of foo_src_compile. An example:
Sometimes, extending default functions by having code execute before and after isn't flexible enough. When dealing with long, complex functions, you often want to have your custom code run in the middle of those functions. Function sections provide for greater flexibility required here. They break the functions down into sections and allow you to execute code between any two sections. The implementation is simple. Let's take as an example the src_compile() function from base.eclass. (Note: it no longer exists, but it's a good example :-) It looks like this:
Here is the same function, divided into sections:
The code has been divided into two sections: configure and make. In our simple example, they correspond to the two commands in the original function. In the center of the new function is a while;case...esac;shift;done block. This block matches the parameters to the function with the defined section names and executes the corresponding lines of code. The special case all calls the same function recursively with a list of sections in order. It's up to the eclass's author to maintain this list. The line before the block says that a call without parameters should be treated the same as a call with the single parameter all. As you see, this function recurses a lot. Note, however, that the call base_src_compile configure all make is also legal; it will execute base_src_compile configure configure make make. Now, in your ebuild (or eclass) that inherits from base.eclass, you get the stub function src_compile which calls base_src_compile without parameters. This makes base_src_compile execute all, that is, all its sections. You can leave it as-is. If you wish to extend it, you can define a new src_compile and call base_src_compile a section at a time:
As you can see, the function sections add flexibility since you can now insert code between the two sections, as well as run them in a different order or run only some of the sections provided. This makes for greater code reuse overall. These are more functions provided by ebuild.sh. They add verbose debug output facilities to eclasses, to allow you to trace their execution more easily without having to read the long traces provided by the bash debug mode. All my eclasses call these functions a lot. debug-print() simply prints all its parameters with the 'debug:' prefix. It is called whenever there's something interesting to put in the debug log. debug-print-function() prints 'debug: entering function $1, parameters: $2 [$3 ....] It is called at the beginning of a function. debug-print-section() prints 'debug: now in section $1'. It is called at the beginning of a function's section. The debug output normally goes into ${T}/eclass-debug.log. You can set the ECLASS_DEBUG_OUTPUT env. variable (in make.globals/conf or in the environment) and output will be sent there as well. You can also set it to the special value 'on', which echoes output to stdout together with the other emerge messages. Let's add typical debug output statements to our sample function:
${FUNCNAME} is a bash built-in that returns the current function's name. Most eclasses are simple, and you should simply read them and maybe glance at a couple of ebuilds using them to understand how they work. Also, most eclasses are well-commented, so it's best to read them. This chapter documents the overall relationship between the kde* eclasses. This eclass defines some default variables and functions, similar to those you'd get by default in a non-inheriting ebuild (which are defined in ebuild.sh). You probably aren't interested in using it directly, but rather through one of the kde eclasses, which inherit it. One interesting bit of functionality it provides is the autopatch capability. If you set the PATCHES variable to contain a list of files in your ebuild that uses base_src_unpack() (or kde_src_unpack()), the sources will be patched from those files. The patches need to work with -p0 when run from ${S}. Note that you can set PATCHES without defining a custom src_unpack() in your ebuild! That is what it's for. The newer epatch() function from eutils.eclass is much more powerful - it supports compressed patches, patch directories and series, and automatic detection of the patch level - and I intend to make autopatch use it sonmeday. Note that the patch section in base_src_unpack() is deprecated and will be removed soon. If you see an ebuild using it, it needs to be converted to the autopatch style. This eclass provides the functionality needed to create 'live' cvs ebuilds. Such ebuilds fetch sources from a specified cvs server at unpack time, thus always getting the latest bugs and fixes from upstream. However, the necessary (versioning etc.) support for live cvs ebuilds has not yet been added to portage. They can work with this eclass, but it is inconvenient in many respects. Think twice before creating a live cvs ebuild; perhaps a regular cvs snapshot would be better. If you intend to add such an ebuild to portage, be aware of the cvs ebuild guidelines in the developer's guide. Before inheriting cvs.eclass, set any non-default settings you want (at least the server address and module name). See the list of configurable settings and default values at the beginning of cvs.eclass, marked as 'ebuild-configurable settings'. After that, things are mostly automatic. A cvs_src_unpack() (no sections) is provided. If you wish to know more, read the eclass itself. This eclass contains all KDE-related helper functions. Some of them you should never need to use directly in an ebuild; these are not mentioned here, and should be well-commented in the source. Note that by 'helper functions' I mean any functions that aren't special ebuild functions (src_unpack() etc.). All kde eclasses containing such 'special' functions inherit kde-functions. The only code outside any functions in kde-functions.eclass (which thus runs on sourcing) is a block that determines whether or not the current ebuild is one from kde-base. If it is, KDEBASE=true is set. This variable is used in various logic tests elsewhere and it is comfortable to have one centralized test for it. The current multi-kdedir scheme A short explanation about the way Gentoo manages multiple KDE versions: A KDE (that is, things from kde-base) live in /usr/kde/${major-version}.${minor-version}. So, fex., KDE 3.1.x lives in /usr/kde/3.1. However, this scheme was established after the KDE 3.0 release, and so older versions live in nonstandard locations: KDE 3.0.x lives in /usr/kde/3 (and not /usr/kde/3.0), and KDE 2.2.2 (the only 2.x version we have) lives in /usr/kde/2. The cvs ebuilds I maintain install into /usr/kde/cvs. Any number of KDEs with different minor versions can thus coexist. kde-base packages have a SLOT of major.minor (e.g. 3.0, 3.1). Since QT versions are supposed to be fully backward compatible across minor versions, we have only one of each major version installed and with a different slot; they live in /usr/qt/$major. A non-kde-base ebuild always installs in /usr. The kde-env package puts KDEDIRS=/usr in env.d, allowing these apps to run properly. The app compiles and links against the latest KDE libraries found; the eclass checks the standard locations in descending order - /usr/kde/cvs, then /usr/kde/3.1, then /usr/kde/3. (kde-base ebuilds will always link against the kdelibs of their own version.) This of course also depends on the parameter given to need-kde() (see below). There are several special variables you can set to change the default settings of this system. Their prime usage is to compile an ebuild against a specific KDE you have installed for testing, but you can also use them to install a KDE in a nonstandard location, and so have, fex., both KDE 3.0.1 and 3.0.2 installed side-by-side. This, again, is most useful for testing and development. All KDE apps (base and non-base) will install into ${KDEPREFIX}, if set. It overrides all other logic in the eclasses. A KDE app (even if it is a kde-base one) will try to link against the kdelibs installed in ${KDELIBSDIR}, if set. If it fails, it will fall back to the default logic of locating the latest kdelibs (or the proper version for kde-base version). need-kde(), need-qt(), set-kdedir(), set-qtdir() kde-functions.eclass provides two pairs of functions: need-kde(), need-qt() and set-kdedir(), set-qtdir(). These functions handle the details of multiple KDEs and QTs setup. The need-kde() function is called with a parameter which is the minimal version number of kdelibs required. It adds the proper dependencies to DEPEND, RDEPEND and call the set-kdedir() function. If no parameter is passed, a version number of 0 (zero) is used, meaning that any version will satisfy the dependency. need-kde() also calls need-autoconf() and need-automake() with the correct parameters for this KDE version. The set-kdedir() function then determines the installation prefix and kdelibsdir location your ebuild should use. These are passed to you in ${PREFIX} and ${KDEDIR}, respectively (and are handled automatically in kde.eclass). Note that no ebuild should ever address ${KDEPREFIX} or ${KDELIBSDIR} directly! need-kde() also looks up the minimal version of QT required for this version of kdelibs from a table. It then calls need-qt() with this version. A qt-only (i.e. non-kde) app's ebuild usually calls need-qt directly, bypassing need-kde. The need-qt() function adds the required QT version to DEPEND, RDEPEND and calls set-qtdir() with it. The set-qtdir() function sets QTDIR to be the default location of this version of QT. Unlike set-kdedir(), set-qtdir() doesn't actually check if there's a QT installed there. need-kde() (or need-qt()) needs to be called from the main part of the ebuild (i.e. not from a function), so that any changes to DEPEND and RDEPEND affect emerge. need-autoconf(), need-automake() These functions set the necessary environment variables to make the requested version of autoconf or automake run. They also unset all previously set variables of this kind. For example, calling 'need-automake 1.4' will set NEED_AUTOMAKE_1_4=1 and unset all other WANT_AUTOMAKE* variables. For more info see the functions' code and the comments at the beginning of /usr/bin/auto{conf,make} (on a Gentoo system). kde_sandbox_patch() Some KDE makefiles are broken. They chmod or chown files in PREFIX when installing, but do not respect DESTDIR (${D}). I.e. when installing, they correctly copy a file to ${DESTDIR}/${PREFIX}/path/foo, but then try to chmod +x the file ${PREFIX}/path/foo on the live filesystem which may not even exist. And if it does exist, the sandbox prevents this operation. This function runs a generic sed on makefiles which fixes all known cases of the problem. It is called with the directories to be processed as parameters, and processes Makefile, Makefile.in and Makefile.am in those directories. For example:
kde_remove_flag() This is used to weed out compiler flags that are known to break packages. You call it after unpacking with the subdirectory of ${S} in which to work as the first parameter, and the name of the flag to remove as the second. Note that it is not recursive. Example: "kde_remove_flag foodir/barfoo -fomit-frame-pointer". kde_remove_dir() and ${KDE_REMOVE_DIR} This function removes the specified subdir from compilation. It deletes it and removes all mention of it from the subdirs file, configure and the makefiles. Note that it only works on subdirs of ${S} for now, not on 2nd level subdirs. You can call it with a list of subdirs to remove; it works on each parameter in turn. You can call it directly, but to avoid having to define a custom src_unpack() just to do that, you can set KDE_REMOVE_DIR to a list of subdirs to remove. kde_src_unpack() will call 'kde_remove_dir ${KDE_REMOVE_DIR}' after unpacking. As you can see, I go to some lengths to avoid having to define an extra function in an ebuild, because this makes the ebuilds much cleaner and more readable. This is the main, central KDE eclass. It contains most of the KDE-related code. All KDE ebuilds inherit it, one way or another. The kde eclass inherits base and kde-functions. As with the other eclasses, read it to find out what it does. Most of it should be self-obvious. Here is a short summary: The eclass's global section (i.e. the one that's executed when you inherit it) adds the correct deps on kde-env, automake, autoconf, make and perl (the last is used by standard configure scripts for fast makefile generation). It also sets the default SLOT="0". kde_src_unpack() basically just calls base_src_unpack(), passing on any parameters (e.g. sections to execute). After that, it adds kde-specific items. It touches all .ui files in the unpacked sources to regenerate any stale .cpp,.h files. It also calls kde_remove_dir() with ${KDE_REMOVE_DIR} if this variable is set (see above in the section on kde-functions). kde_src_compile() also has several fixes. One is exporting kde_widgetdir="${KDEDIR}/lib/kde3/plugins/designer" to get around a bug in older kde acinclude.m4.in's. Another is setting HOME="${T}/fakehome", so that any accesses to ${HOME}/.kde and ${HOME}/.qt aren't stopped by the sandbox, and don't affect the user's home directory. It is a bug (or shortcoming) of uic that it always tries to access config files in these locations. kde_src_compile() has several sections. myconf adds to ${myconf} the default kde configure script parameters, such as --prefix=${PREFIX} (remember, ${PREFIX} is set by set-kdedir()). You can add your own values to ${myconf} either before or after this section; just remember never to overwrite old values, because users can expect to set ${myconf} in the shell and in this way add something to the configure parameters used by the ebuild. The configure section runs the configure script in ${S}, passing ${myconf} to it. If the configure script does not exist, it tries to generate it by running make -f Makefile.cvs or make -f admin/Makefile.common. Thus, this stage of compilation (which is needed for cvs snapshots, or ebuilds that patch files like configure.in) is also done automatically. The make section simply runs emake || die. Finally, there is an all section which runs all of the above. Finally, kde_src_install() has a make section which runs make install, and a dodoc section which runs dodoc on some standard doc names in ${S}, such as README and COPYING. This eclass is now deprecated, ebuilds should "inherit kde" instead. This eclass is for the core kde distribution packages in kde-base/*. It inherits kde. It sets the correct DESCRIPTION and HOMEPAGE and calls need-kde ${PV}. The simpler, smaller kde-base/ packages (e.g. kdetoys) don't need to make any changes to it; most of those that do only add deps and patches. This eclass is for the kde-i18n-* packages. In fact, all kde-i18n ebuilds are completely identical and so all they have to do is inherit from this eclass. Their ${P}, ${P}, ${PV} variables do the rest. This eclass is also deprecated, and all the code has been moved to kde-dist.eclass. This eclass is meant for the koffice-i18n-* packages and is very similar to kde-i18n.eclass. Again, all kde-i18n ebuilds are completely identical and so all they have to do is inherit from this eclass. This eclass works on top of cvs.eclass, adding some kde-specific functionality. For example, it automatically fetches the admin/ dir from the kde-common module of kde cvs. Read the eclass to find out more, including kde-cvs-specific settings you can pass to it. This chapter explains how to write standard KDE ebuilds. All that is said here is mostly a rehashing of the information about eclasses above. When in doubt, look at other ebuilds, at the eclasses, or ask. The code below should be obvious after reading this howto:
Some ebuilds end right here. Others need some customization. The next stage is to add any extra deps. Remember: *always* extend variables, never override! Because our goal is to avoid defining custom ebuild functions unless we have to, we set all the settings we can, and call all the helper functions we can, directly from the ebuild's main section. Remember though that there are limitations on code in the main section; for example, it must not produce any output (debug-print() output probably doesn't count though).
We also want to add some extra arguments to myconf, which are then passed to configure (assuming that we use kde_src_compile's configure section):
We also have a patch to add. If it can be applied using -p0 in ${S}, we can use base_src_unpack's autopatch section. Remember, kde_src_unpack() calls base_src_unpack() passing on any parameters you gave it.
Finally, we want an extend src_install() to put in place some documentation:
Let's look at the ebuild we have created in this example:
A typical ebuild with optional KDE functionality When adding kde (eclass) functionality to an existing ebuild, you should simply prefix each kde-specific line with use kde && , or create whole if [ -n "`use kde`" ]; then; fi blocks. To the general section, add the following (only if USE kde is set, of course):
Then, tell your app to look for KDE in the ${KDEDIR} setting that is available after calling need-kde(). If you do not want the kdelibs dep to be added, call set-kdedir() instead of need-kde(). 3. Common ebuild Mistakes3.a. Common Ebuild Writing Mistakes Here is a list of common ebuild mistakes that are common in user-submitted ebuilds. Please make sure the ebuilds you submit don't violate any of these. Before submitting any ebuilds, make sure you read the Gentoo ebuild Development Policy and the Gentoo ebuild HOWTO. Also, make sure you read a couple (eg. more than one or two) of the ebuilds in the tree to make sure you know the style that ebuilds are written in. Also it would be useful to read a couple of ebuilds that use eclasses and understand how to use them by reading the Eclass HOWTO. Finally, you must read the Contributing Ebuilds Guide carefully before submitting your ebuild(s). When you submit your ebuilds, the header should be exactly the same as the one in /usr/portage/skel.ebuild. Most importantly, do not modify it in any way and make sure that the $Header: $ line is intact. The first three lines must look like this:
Only if you are submitting a patched or version bumped ebuild, should you not need to modify the $Header: $ line. But the line must be present. When we check the ebuild into CVS, it will modify that header with the appropriate version and date information. So there is no need for you to manually modify it. By far the most common omission is the IUSE variable. You must (according to the Gentoo ebuild HOWTO) include the IUSE variable even if there are no USE flags in use. If there are no USE flags supported, then just add the following:
You should never redefine those variables. Always use MY_P, MY_PN, MY_PV, P0, etc. See other ebuilds that do it in portage for more information. Most ebuilds use bash "Parameter Expansion". Please read the man page for bash to understand how "Parameter Expansion" works. By the way, if you find a package that re-defines it, don't copy it. Submit a bug about that ebuild. Including version numbers in SRC_URI and S You should try not to include version numbers in the SRC_URI and S. Always try to use ${PV} or ${P}. It makes maintaining the ebuild much easier. If a version number is not consistent with the tarball/source, then use MY_P. An example dev-python/pyopenal fetches a tarball called PyOpenAL, so we redefine it like:
There are many things that go wrong with user submitted DEPEND and RDEPEND fields. Here are some important points to follow when you write the dependency part.
This is another very common error. The ebuild submitter submits an ebuild that "just works" without checking if the dependencies are correct. Here are some tips on how to find the correct dependencies.
Another common mistake users make when submitting ebuilds is supplying an invalid license. For example, GPL is not a valid license. You need to specify GPL-1 or GPL-2. Same with LGPL. Make sure the license you use in the LICENSE field is something that exists in /usr/portage/licenses. As a tip, check the COPYING in a source tarball for the license. If a package does not specify it uses GPL-1 or GPL-2, it is very likely it uses GPL-2. If the license for the package you submit is unique and not in /usr/portage/licenses/, then you must submit the new license in a separate file. Please do not add other ARCHs into KEYWORDS unless the ebuild has been tested on that ARCH. Also all new ebuilds should be ~x86 or whatever architecture it is. Make sure when you bump a version, the stable KEYWORDS are all marked as ~. Make sure you have the SLOT variable in the ebuild. If you don't plan to use it, don't remove it. Put in:
DESCRIPTION and HOMEPAGE wrong Please check the if the HOMEPAGE variable is right and leads users to the right page if they want to find out more about the package. And make sure the DESCRIPTION is not overly long. Good descriptions will describe the main function of the package in a sentence. Wrongfully used spaces instead of TABS It is no fun reformatting lines of ebuilds because the submitter did not follow the guidelines to use TABS rather than spaces. So please use tabs! I'm often guilty of this. Remember to run repoman over your ebuilds so it can tell you if there is trailing whitespace at the end of lines or on empty lines. Adding redundant S=${WORKDIR}/${P} If S=${WORKDIR}/${P}, then you should not add it to your ebuild. This is implied already, you should only add it if it is something other than ${WORKDIR}/${P}. If your package has documentation, make sure you install it using dodoc or in /usr/share/doc/${PF}. Remember to check for errors when running dodoc/doins. 3.b. Common Ebuild Submission Mistakes Please submit ebuilds properly by following the Contributing Ebuild HOWTO on the Gentoo Docs Page. Please please please do not attach ebuilds as tarballs. Attach patches separately as well so we can easily examine them. Don't cut and paste an ebuild into bugzilla's comment field. No description on what the package is Please let us know what the package is, and fill in the URL with the home page of the application, if any exists. Package updates without changing the ChangeLog If you submit a package update, then make sure you explain what changes you made to the ebuild. For example if a package introduces a new features/option and you use a USE flag, list it in your bug. Don't make us hunt for it. It is wise to submit a diff for a package update rather than the whole ebuild. The best way to generate it would be:
Submitting unchanged ebuilds for version bumps If you are submitting a new version for a package in portage, make sure the existing ebuild works and make sure changes are incorporated in the new ebuild (such as added documentation.) If there are no required changes to the ebuild from the previous version, then don't attach the ebuild. Just say so in the bug report that you copied the ebuild over and verified that the package works and installs properly. Comments, corrections and suggestions should go to Alastair Tse. 4. Gentoo Metadata4.a. Why the need for metadata.xml? The metadata.xml file has as its purpose to give extra information about ebuilds. The metadata.xml file should exist in every package directory. A skel file can be found as skel.metadata.xml in the portage tree. A metadata.xml file can contain a number of tags:
There are also some attributes that can be used with these tags. They are all optional:
In this first example we provide you with the metadata.xml for OpenOffice of which the ebuilds are completely managed by a herd called openoffice:
The openoffice herd is defined in herds.xml by the Gentoo Metastructure Project:
If you want to add (or remove) yourself from a herd, edit herds.xml located in [gentoo]/xml/htdocs/proj/en/metastructure/herds in Gentoo's CVS repository. Make sure you know the e-mail alias the herd listens to (for instance the "sound" herd has sound@gentoo.org) and add yourself to the alias (by editing /var/mail/alias/misc/<alias name> on dev.gentoo.org). For the second example, we will examine the metadata.xml of app-portage/mirrorselect. This ebuild is maintained by the tools-portage herd, but has a separate maintainer.
For the third example, we will describe the metadata.xml of sys-apps/hal. This ebuild is maintained by the gentopia herd and contains USE flag descriptions.
This example demonstrates the usage of the upstream element:
5. Ebuild Maintenance HOWTOThis guide aims to explain common everyday ebuild maintenance routines, as well as other rarer maintenance routines which developers may not be familiar with. When adding a new ebuild, you should only include KEYWORDS for architectures on which you have actually tested the ebuild, confirming that it works as it should and that USE flags are properly honoured in the resulting package which would be installed. If possible, you should give the actual library or application thorough testing as well, since you would be responsible for any breakages for your architecture(s). Minimal testing such as checking that the application starts up without any errors should always be performed. If you are adding a user-submitted ebuild, do not assume that the submitter has done testing on various architectures: often, KEYWORDS are cloned across packages or generated from documentation in the source packages, which does not signify that the package does indeed work on those architectures. Only architecture maintainers for a given architecture should mark packages as stable on that architecture. The maintainer of the package should always be contacted just in case there are reasons not to do so. The exception to this is if you are part of an architecture team, in which case you may mark the package stable for that architecture. If you are not part of an architecture team, you should consult the guidelines below; if the architecture you are looking for is not listed then please consult the relevant lead. You should never stabilize packages on architectures for which you cannot test and instead you should file a bug to the relevant architecture team, such as sparc@gentoo.org asking them to stabilize the ebuild. Alternatively, you may be able to find Gentoo developers on IRC who could help you with your request. It is best to not use arch-maintainers@gentoo.org, adding architecture teams onto a bug's CC list individually instead. That way teams can remove themselves from the list when they are done, giving a clear indication of which teams still have to stabilize a package. SPARC: You must have prior permission from the arch lead (currently Weeve). Usually we expect you to be on the sparc alias for QA reasons, although other arrangements can be made if you will only be working with a small group of packages. ALPHA: Maintainers may keyword their own packages but are reminded to inform the Alpha team if they can help out with testing and keywording packages so the team can keep an eye out for possible keywording mistakes. MIPS: You must have prior permission from any senior MIPS developer. Because of the massive range of hardware involved, being on the mips alias and having access to a variety of MIPS systems are generally requirements. New ebuilds should rarely go in with "arch" keywords and even if they do not, the package must be tested on any architectures listed in the KEYWORDS variable of the new ebuild. Exceptions to the no "arch" rule are major bug fixes, or security fixes. If the previous version of the ebuild contains KEYWORDS which you cannot test for, you should downgrade them: turn any "arch" keyword to "~arch". If you think that your package may not work at all even on "~arch" then it is best to leave the keyword out and request testing from the relevant team: if you are to do this, you must file a bug to the team in question. If a new version introduces new dependencies which are not available on some architectures, then you should file a bug or ask on IRC before you upgrade the package. If you really need to get the ebuild added in a hurry, for example, for a security fix, then you should drop any KEYWORDS which are causing problems and CC the relevant architectures on the bug - you should file a new bug to the architecture in question regarding this if no bug is already available. If there are no new dependencies, do not remove keywords if your commit fails with repoman - please try a full cvs update and if you still have problems, then commit with repoman -I and file a bug to the broken architecture, noting it in your CVS commit message.
Moving ebuilds is a two-step process: Firstly, you need to move the ebuild in CVS. To do this, you should copy the ebuild to its new location and commit that as you would with a new ebuild. After this, you should change any ebuilds which DEPEND on the old ebuild to depend on the new one. After this, should add an entry to the latest file in profiles/updates/ in the Portage tree in the in the following format:
This example would transparently move net-misc/fwbuilder to net-firewall/fwbuilder if users have it installed. This way, users would now automatically receive updates for net-firewall/fwbuilder when they are available. Once this step is concluded, you are allowed to remove the old package. Simply issue a cvs remove -Rf $PN in the package category and commit the changes afterwards with a meaningful commit message.
When removing an ebuild make sure that no dependencies in Portage are broken due to the removal - additionally, your CVS commit message should explain clearly why the ebuild is being removed from CVS. If you need to remove ebuilds, make sure you do not accidentally remove the newest/only stable ebuild for any architecture. If you would like to get a newer version marked stable, then please file a bug or ask on IRC. You should also not cause an unnecessary downgrade for any "~arch" when removing ebuilds - instead, it is best to get the newest version marked "~arch" first and then remove redundant versions of the ebuild. When removing an ebuild make sure that no dependencies in Portage are broken due to the removal - additionally, your CVS commit message should explain clearly why the ebuild is being removed from CVS. In order to remove a package completely from CVS, delete any files from the directory and commit this, CVS will take care of removing empty directories itself.
When you encounter a package that is trying to install files that are already provided by another package (detectable with FEATURES=collision-protect for example) you have to fix this situation before you can commit the ebuild or, if you encounter this with an existing package, file a bug about that package (see below for a few exceptions). The reason file conflicts are critical is because if "foo" provides the file /usr/bin/example and "bar" is going to overwrite it, and later "bar" is unmerged, Portage will remove /usr/bin/example and it is therefore likely it will break "foo". The most obvious fix is to add a blocking dependency to both packages that want to install that file, so they can't be installed at the same time. But unless there are also other reasons for those packages to block each other you should avoid this if possible and rather fix the package, which could include one or more of the following steps:
In some cases conflicting files can't be really fixed or aren't critical, currently known exceptions are Perl module manpages (overwriting the ones from Perl itself) and CONFIG_PROTECT'ed files (which should still be fixed, but aren't critical as Portage won't overwrite them). 6. Manifest Signing GuideRequirements:
Key Setup:
Portage Configuration:
Now you should be able to sign your Manifests on repoman commit. Repoman will ask you for your passphrase before committing the Manifest. This step is after it has committed the other files. At the moment repoman doesn't check if the Manifest is already signed, so others are able to "unsign" your package later. This will change before signing is made mandatory. C. Policies1. Ebuild policyHere are some general development guidelines to follow:
On some architectures, shared libraries must be built with -fPIC. On x86 and others, shared libraries may build without -fPIC. This can be wasteful and potentially cause a performance hit. If you encounter a package that is not building shared libraries with -fPIC, patch the Makefile to build only the shared libraries with -fPIC. More information on PIC is available at http://www.gentoo.org/proj/en/hardened/pic-internals.xml. If you are unsure, please ask in a public developer forum (like the gentoo-dev mailing list or #gentoo-dev irc channel) for help. New Perl modules are to be added to portage only when one of the following conditions is met:
Please make sure that at least one member of the perl herders approves your addition. Ebuild file names consist of four logical subsections: pkg-ver{_suf{#}}{-r#}.ebuild
The first subsection, pkg, is the package name, which should only contain lowercase letters, the digits 0-9, and any number of single hyphen (-), underscore (_) or plus (+) characters. Examples: util-linux, sysklogd and gtk+. We have some packages in Portage that don't follow these rules, but your packages should. The second subsection, ver, is the version of the package, which should normally be same as the version on the main source tarball. The version is normally made up of two or three (or more) numbers separated by periods, such as 1.2 or 4.5.2, and may have a single letter immediately following the last digit; e.g., 1.4b or 2.6h. The package version is joined to the package name with a hyphen. Examples: foo-1.0, bar-2.4.6. The third subsection, {_suf{#}}, is optional may contain one of these predefined suffixes, listed in least-recent to most-recent order:
Any of these suffixes may be immediately followed by a non-zero positive integer, e.g., linux-2.4.0_pre10. Assuming identical version parts, the suffixes are ordered as follows (lower means older): _alpha < _beta < _pre < _rc < (no suffix) < _p. When comparing identical suffixes with trailing integers, the one with the larger integer will be considered most recent. Example: foo-1.0_alpha4 is more recent than foo-1.0_alpha3. The fourth subsection of the package name is the Gentoo Linux-specific revision number ({-r#}). This subsection, like the suffix, is also optional. # is a non-zero positive integer; e.g., package-4.5.3-r3. This revision number is independent of the version of the source tarball and is used to inform people that a new and improved Gentoo Linux revision of a particular package is available. Initial releases of ebuilds must have no revision number; e.g., package-4.5.3 and are considered by Portage to have a revision number of zero. This means that counting goes as follows: 1.0 (initial version), 1.0-r1, 1.0-r2, etc. Package revision numbers should be incremented by Gentoo Linux developers when the ebuild has changed to the point where users would want to upgrade. Typically, this is the case when fixes are made to an ebuild that affect the resultant installed files, but the ebuild uses the same source tarball as the previous release. If you make an internal, stylistic change to the ebuild that does not change any of the installed files, then there is no need to bump the revision number. Likewise, if you fix a compilation problem in the ebuild that was affecting some users, there is no need to bump the revision number, since those for whom it worked perfectly would see no benefit in installing a new revision, and those who experienced the problem do not have the package installed (since compilation failed) and thus have no need for the new revision number to force an upgrade. A revision bump is also not necessary if a minority of users will be affected and the package has a nontrivial average compilation time; use your best judgement in these circumstances.
Ebuilds should be based on the previous version of the ebuild to ensure that fixes aren't dropped accidentally. Fixes should include appropriate comments in the ebuild explaining what they are for and why they are needed. If you are not familiar with the fixes, or unable to determine if they are still needed, you should not be updating the ebuild. Portage supports a concept called "virtual" packages. Using virtual packages, it is possible to have a particular category/package name map to another. Here's an example of how to use virtual packages. Let's say you create a new cron package called foocron. Gentoo Linux is currently set up so that things that need a cron package of some kind depend on the virtual/cron package. This allows ebuilds to ensure that there is some kind of cron available while allowing users the flexibility to install the cron package that they prefer. To plug your foocron-1.0.ebuild into this system, you'd add a line to the ebuild that reads:
Now, when foocron-1.0 is installed, the virtual/cron package will be registered. If you didn't have any cron package installed before, this would mean that any package DEPENDing on virtual/cron would have that dependency fully satisfied. Note that it is advised to only specify a PROVIDE value for defined virtuals (see /etc/make.profile/virtuals). Also please note that (a) PROVIDE isn't to handle renaming of packages and (b) don't use it with new style virtuals. There is a second component to the Gentoo Linux virtuals implementation. What would happen if there were no installed package that provided virtual/cron? How would Portage choose the "correct" cron to install to satisfy the virtual/cron dependency? Portage takes care of this situation by using a profile-specific virtual mapping file called virtuals which is stored in the profile directory /etc/make.profile. If you take a look at your virtuals file, you'll find that the contents look something like this:
The first line of this file tells Portage that if a package depends on virtual/lpr and no virtual/lpr is installed and no virtual/lpr package is available in the Portage tree, then net-print/cups should be installed to satisfy this dependency. net-print/cups contains a line that reads PROVIDE="virtual/lpr" so that future dependencies on virtual/lpr will be satisfied. Now for the developer guidelines. If you were to add the foocron package, you would obviously want to ensure that all programs that depend upon virtual/cron are able to work correctly with it. And if you were to add a package named foobarosity that depended on virtual/cron, you should likewise ensure that all packages that provide virtual/cron will be satisfactory for the proper functioning of foobarosity. Before creating new virtual packages, please begin a discussion on the internal developer mailing list about that virtual. Keeping developers informed of new virtuals is essential to ensure their uniform use. Whenever an ebuild is sourced, the functions and variables within it are loaded into memory by the script interpreter. However, only variables and instructions that are not part of a function are interpreted - functions such as src_compile() are only executed by Portage when the ebuild has reached the compile stage. The code within these functions are considered in "local scope" while everything outside of the functions is in the "global scope" meaning they are executed every time the ebuild is sourced. An external application (such as grep, sed or awk) should never be called in global scope for performance reasons, and alternatives such as using built-in bash replacement should be used instead. Useful alternatives can be found in the Advanced Bash Scripting Guide. Additionally, any external application that may be called in global scope can not be guaranteed to exist on the system. If the command is placed in local scope (for example, in the pkg_setup() function), we can guarantee its presence by placing it in the ebuild's ${DEPEND}. There are two different ways to build an ebuild based on sources from a CVS development tree. The first and traditional way is to create a "CVS snapshot" ebuild by creating your own tarball snapshot of the upstream CVS tree, mirroring the sources on our official distfile repository, and writing an ebuild to specifically use this tarball snapshot. These types of CVS ebuilds will be referred to as "CVS snapshot ebuilds" below. The other method of creating a CVS-based ebuild is to use cvs.eclass to create a "live" CVS ebuild. Such an ebuild will dynamically grab the latest development sources from a CVS repository at "fetch" time, ensuring that the sources are as up-to-date as possible. These types of CVS ebuilds will be referred to as "'live' ebuilds" below. The following paragraphs detail the policy relating to the use of CVS-based ebuilds. Note that there are strict rules relating to the addition of such ebuilds to the Portage tree. Snapshot cvs ebuilds are greatly preferred over "live" cvs.eclass cvs ebuilds. Snapshot cvs ebuilds are allowed if a cvs snapshot contains known fixes that are needed for proper operation of a software package, or if the cvs version of a particular software package is known to or has been proven to simply "work better" than the normal release version. "Live" cvs.eclass ebuilds are generally only intended for the convenience of developers and should always be masked with a ~[arch] keyword. It is impossible to guarantee the reliability of a "live" cvs.eclass ebuild since the upstream cvs tree may change at any time, which is why they should always be masked. Whether a "live" CVS ebuild or a "snapshot" CVS ebuild, you the developer are responsible for ensuring that the ebuild works correctly. This is particularly difficult to do with "live" cvs ebuilds for obvious reasons. If ebuilds (of any kind) do not work correctly or are flaky, they should be fixed or removed from the Portage tree. If they are "live" ebuilds, they may be ~[arch] keyword masked for their lifetime (this special exception is detailed below). If a user or users specifically request a "live" cvs ebuild, you can add one for them. It should have a ~[arch] keyword so that other users don't merge it unsuspectingly. This way, the user(s) requesting them (likely developers) can install them but other users will be protected from merging them accidentally. Again, this only applies to situations where a user or users specifically request a "live" cvs.eclass CVS ebuild. Snapshot ebuilds should only be added to the Portage tree with the intention that they are stable and provide better functionality than the normal release versions of said software.
User-submitted ebuilds should never be blindly trusted and should always be well-tested and audited before being committed to CVS. If a user-submitted ebuild has problems, you will be held accountable. By committing it to CVS, you are vouching that the ebuild meets all Gentoo Linux development standards. Make sure that the user-submitted ebuild doesn't contain custom headers like this:
This information should be added to the ChangeLog using proper ChangeLog comment syntax. Always ensure that the ChangeLog gives proper credit to the user who submitted the ebuild. This information should appear in the first ChangeLog entry. Also ensure that any new ebuilds you commit contain the following line:
Quite a few user-submitted ebuilds are based on files from rsync, which can contain incorrect header lines. Encourage users to submit diffs to existing ebuilds if they are submitting an upgrade. By doing this, we can help avoid the re-introduction of previously-fixed bugs into our "new" ebuilds. If you are not working from a user-submitted diff but a complete ebuild, then use the diff command to see what has changed, keeping an eye open for anything from our current ebuild that should appear in the new ebuild, or anything in the new ebuild that should be fixed or removed. In general, let the user do the work required to get his or her ebuild up to par, unless you want to clean up the ebuild on his or her behalf. Even so, it's often better to have the user do the work so that they can learn from their mistakes and submit cleaner ebuilds in the future. Be sure to be thankful for any submission, even if it isn't very good. Be polite but honest -- if an ebuild isn't usable, the user can be told in a way that does not insult their current ebuild-writing abilities. Remember that the user who submitted that broken ebuild may be a skilled and productive member of our project in the future -- that is, if they receive the right amount of encouragement and support and continue to improve in their abilities. Portage / baselayout release policy Only members of the Portage team (who know who they are) have the authority to release new releases of Portage. No one else is allowed to roll new releases of Portage. Only members of the baselayout team (who know who they are) have the authority to release new releases of baselayout. No one else is allowed to roll new releases of baselayout. /usr/portage/profiles/package.mask contains a list of packages that should not be merged by users and comments detailing the specific reason why. Package.mask is used to prevent merging of packages that are broken, break something else, or badly need testing before going into ~ARCH KEYWORDS in the tree. When adding to package.mask, always commit package.mask prior to committing the masked ebuild. This prevents the ebuild from hitting users before the updated package.mask does. Great care must be taken any time a package is removed from package.mask. Keep in mind that if an ebuild is in package.mask, it's there for a reason. If you didn't mask the ebuild, always contact the developer listed in the package.mask comments prior to taking any action. Additionally, if the masked ebuild is a core package, a dependency of a core package, or the unmasking has any possibility for adverse effects, the change must be discussed internally on the developer mailing list. The purpose of ~arch is for testing new packages added to Portage. There is a difference between using package.mask and ~arch for ebuilds. The use of ~arch denotes an ebuild requires testing. The use of package.mask denotes that the application or library itself is deemed unstable. For example, if gimp-1.2.0 is the stable release from Gimp developers, and a new bug fix release is available as 1.2.1, then a developer should mark the ebuild as ~arch for testing in portage because the release is deemed to be stable. In another example, if Gimp decides to release an unstable/development series marked as 1.3.0, then these ebuilds should be put in package.mask because the software itself is of development quality and is not recommended by the developers for distribution. Any new package that enters Portage must be marked ~arch for the architecture(s) that this version is known to work on. The developer who commits the ebuild must verify it is in working order, and the KEYWORDS are correct. Moving package versions from ~ARCH to ARCH When a package version has proved stable for sufficient time and the Gentoo maintainer of the package is confident that the upgrade will not break a regular Gentoo user's machine, then it can be moved from ~ARCH to ARCH. An indication of the package's stability would be no verified or unresolved bug report for a month after the version's introduction. It is up to the maintainer of the package to deem which versions are stable or if development versions should be in package.mask or left in ~arch. You must also ensure that all the dependencies of such a package version are also in ARCH.
Gentoo Linux policy requires that all ebuilds contain KEYWORDS, LICENSE, and SLOT variables. HOMEPAGE, SRC_URI and DESCRIPTION should also be included except for special circumstances. DEPEND (and if necessary, RDEPEND) should be included if your package has any build or runtime dependencies, respectively. Use DEPEND to define the dependencies required for building a particular package, and set RDEPEND to the dependencies required to run a particular package. RDEPEND should be set explicitly, even if RDEPEND=${DEPEND}.
It's also important to note that only RDEPEND dependencies are satisfied when one installs a binary .tbz2 package; use this information to help you choose the correct RDEPEND dependencies. A package should depend upon the oldest version that satisfies the dependency. If it works with libfoo-1.2.x, don't depend on libfoo-2.x just because that's what you have installed. In general, packages should depend on =libfoo-1.2* instead of >=libfoo-1.2. Otherwise, things may start breaking horribly when libfoo-2.0 is introduced. Depending on a virtual package entry like virtual/foo will only work when the different packages providing virtual/foo have identical interfaces. Consider virtual/jdk-1.3 for example. Some packages don't work with ibm-jdk-1.3 while they do work with sun-jdk-1.3. For this reason, be sure that your package is tested against all virtual providers before unmasking. It may be possible to only depend on a subset of those packages in the virtual rather than the virtual itself. 2. Etiquette policy2.a. Introduction and some simple suggestions These suggestions are designed to be an easy-to-follow guide to what Developer Relations would expect to be good developer etiquette. They should cover most areas and should be employed wherever they can be. That doesn't mean that we expect you to follow this guide to the bullet point; nor do we expect you even agree with it - we do expect, however that all developers maintain reasonable standards of behaviour with our community - whether to other developers or users. However, you may be subject to sanctions or a suspension if a reasonable standard is not met. By reasonable standards we don't want you to feel that we are not allowing you to say anything, rather, we believe that how you say it, and the method and professionalism in how you express your opinion defines whether you meet the reasonable standards or not, since, as a developer, what you say and do reflects upon Gentoo and the project as a whole. We just require you to be equally respectful to developers and users alike, and to value the opinion of everybody - even if you think it's totally wrong. You should try to use good spelling and grammar everywhere: whether in a CVS commit message, a ChangeLog, or even on IRC if you want to be really nice and make somebody's day. But don't worry; we won't really mind if you don't. You might not notice it, but by taking some effort to clean things up, the amount of time it takes to read your sentences is greatly lowered. However, it is also important not to lose the rope at the same time and make something too eloquent that takes too long to parse. 2.b. What you should try not to do One should try to not be rude, abusive or impolite under any circumstances. Sometimes, just one sarcastic comment can change the tone to the reader. If you think you might give somebody a bad as a result of your comment, and if you really need to say it, make sure people understand that you are not trying to be offensive. Please remember that you are an official representative of Gentoo. In this capacity, you are expected to maintain a certain level of professionalism and courtesy in your day-to-day interactions with users and other developers.
The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license. |
|
