Project:ComRel/Developer Handbook/Help for new developers
This section provides help and instructions for developers working with CVS.
Environment
Profile
Gentoo has decided to provide a developer profile for developers who will be working on packages. This can be set via the developer eselect profile target:
root #eselect profile set default/linux/amd64/13.0/developerNext, rebuild the world set:
root #emerge --ask --update --newuse --deep @worldPermissions
Portage group
As a developer is a good idea to not work on development as the root user. Be sure your user is in the Portage group:
root #gpasswd --add <username> portageThis will provide the ability to create new files in the /usr/portage/distfiles directory. It is necessary by various Portage tools. Be sure to logout and relogin to your so that the group change will take effect to your profile.
Using CVS
Introduction
This 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.
Configuration
Typically, you'll want something along these lines in your ~/.cvsrc:
~/.cvsrcLocal CVS config filecvs -q -z0
diff -u -B
checkout -P
update -d -P
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.
Checking out from CVS/SVN
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.
Checking out gentoo-x86:
user $cvs -d username@cvs.gentoo.org:/var/cvsroot co gentoo-x86Before 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:
Updating in gentoo-x86:
user $cd gentoo-x86
user $cvs update
Gentoo also offers subversion services for those who prefer SVN over CVS. Many core projects such as portage and baselayout are hosted here now.
Check out portage:
user $svn co svn+ssh://username@cvs.gentoo.org/var/svnroot/portageUpdating Portage
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:
/etc/portage/make.confUpdate for use with CVSSYNC="cvs://you@cvs.gentoo.org:/var/cvsroot"
CVSROOT=":ext:you@cvs.gentoo.org:/var/cvsroot"
Due to the fact that the cvs checkout has no metadata cache, portage may become really slow.
On supported architectures, you should also have sandbox in your FEATURES to ensure ebuilds do not modify the root filesystem directly.
Adding/Removing packages
Say you're ready to add a brand new package, foo, in app-misc. To add a package replace the CVSROOT variable with the location of your checked-out CVS tree:
user $cd ${CVSROOT}/app-miscAlways update before working in part of the CVS tree!
user $cvs update
user $mkdir foo
Here, we add the package directory foo to the CVS repository:
user $cvs add foo
user $cd foo
It's better to keep in-progress ebuilds in an overlay outside of your CVS tree:
user $cp /path/to/foo-1.0.ebuild ./Make sure PORTDIR_OVERLAY value is set to the CVS directory when creating manifests:
user $repoman manifest
user $${EDITOR} metadata.xml
You don't necessarily need a files directory any more:
user $cvs add foo-1.0.ebuild metadata.xml filesDon't forget to create a ChangeLog - see the man page for echangelog:
user $echangelog "New ebuild for foo. Ebuild written by me. Fixes bug #XXXXXX."See the Gentoo Metadata section for more information on the metadata.xml file.
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? To removing old versions:
user $cd $CVSROOT/app-misc/foo
user $cvs update
user $cvs remove -f foo-1.0.ebuild
And now you're ready to commit (see the section on Commits below).
Commits
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; the keychain article may be of some assistance if this is the case.
When using repoman, make sure there are no root-owned files present prior to running repoman! "scan" scans the current directory for QA issues. "full" is more complete.
user $repoman scanThe commit option does a scan, then commits, while also updating the Manifest. Make sure you add a verbose and useful CVS ChangeLog message...
user $repoman commitSpeeding CVS up
If you have noticeable 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 snippet given below to your config.
~/.ssh/configHost cvs.gentoo.org
ControlMaster auto
ControlPath ~/.ssh/master-%r@%h:%p
ControlPersist 3600
Miscellaneous
Overlay file permissions
In the case that file permissions inside an overlay get messed up (say for whatever reason chmod -R 777 * was ran), they be fixed using a combination of chmod and the find command. Navigate to the base of the overlay/repository and issue:
user $chmod 744 $(find . -type d) && chmod 644 $(find . -type f)Putting files on mirrors
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.
Mail and web
Our infrastructure allows developers to manage their own mail. Infra project's Developer email article contains instructions on configuring an @gentoo.org email address.
Developers have access to webhosting via http://dev.gentoo.org/~$DEV_USERNAME. Please see the Webspace configuration guide for details.
This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Seemant Kulleen, Shyam Mani, Karl Trygve Kalleberg, Mike Frysinger, Alastair Tse, Paul De Vrieze, Nicholas D. Wolfwood, Marius Mauch, Daniel Black, Wernfried Haas, Chrissy Fullam, Łukasz Damentko, Daniel Robbins, Markos Chandras, John P. Davis, Tim Yamin, Jorge Paulo, Zack Gilburd, Benny Chuang, Erwin, Jon Portnoy, Carl Anderson, Donny Davies, Peter Gavin, Dan Armak, Owen Stampflee, and Ciaran McCreesh on May 10, 2013
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.