DragonFly On-Line Manual Pages

NAME

development -- quick starter for development with the DragonFly codebase

DESCRIPTION

DragonFly uses the git(1) distributed revision control system. If it is
not already on the system, it needs to be installed via dports(7)
(devel/git).
The EXAMPLES section gives initial information to get going with develop-
ment on DragonFly. Please refer to the git(1) manual pages and other
related documents for further information on git's capabilities and how
to use them. The SEEALSO section below has some links.
For information on how to build the DragonFly system from source code,
see build(7). For information on how to build the LiveCD, LiveDVD or
thumb drive image, see release(7).
For a specification of DragonFly's preferred source code style, refer to
style(9). An emacs(1) function to switch C-mode to this style (more or
less) can be found in /usr/share/misc/dragonfly.el. For vim(1) users, a
/usr/share/misc/dragonfly.vim is available.

EXAMPLES

A fresh copy of the repository can be cloned anywhere. Note that the
directory to clone into (/usr/src in the following example) must not
exist, so all previous work in this directory has to be saved and the
directory be removed prior to cloning. Also note that while the main
repository is on crater, it is recommended that one of the DragonFly mir-
rors be used instead.
Simple setup and updating of local repository is done using
/usr/Makefile:
cd /usr
make help # get help
make src-checkout # initial setup
make src-update
Somewhat finer control can be achieved using git(1) directly. To clone
the repository and check out the master branch (this will take some
time):
cd /usr
git clone -o crater git://crater.dragonflybsd.org/dragonfly.git src
cd src
The repository can be held up to date by pulling frequently (to set up a
cron(8) job, git(1)'s --git-dir option can be used):
cd /usr/src
git pull
It is not recommended to work directly in the master branch. To create
and checkout a working branch:
git checkout -b work
To create and checkout a branch of the DragonFly 2.0 release (called
rel2_0):
git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0
Branches can be deleted just as easy:
git branch -d work
After changes have been made to a branch, they can be committed:
git commit -a
git-commit(1)'s -m and -F options can be used to specify a commit message
on the command line or read it from a file, respectively.
Finally, branches can be merged with the (updated) master by using
rebase:
git checkout master
git pull
git checkout work
git rebase master

VENDOR IMPORTS

When importing vendor sources, make sure that you don't import too many
unnecessary sources. Especially test suites that are not used by the
DragonFly build are good candidates for being stripped away. These
instructions assume that you have already extracted the source package
into its final directory and that they are trimmed appropriately.
Donotchangethevendorsourcesbeforeimportingthem on the vendor
branch! Necessary changes to the vendor sources can be applied to master
after the import.
For the following commands, we will import the imaginary package foo-2.3
into /usr/src/contrib/foo. If this is the first import of foo, you will
have to choose the name of the vendor branch. Customarily, this will be
vendor/FOO. However, if you intend to maintain multiple vendor sources
for the same package concurrently, you should choose a branch name which
includes part of the version, i.e. vendor/FOO2.
As a first step, we trick git to work on the vendor branch instead of on
master. Be careful, since after issuing this command all your commits
will go to the vendor branch, but you will commit thewholeworkingtree
and not just the vendor sources! Thus you have to specify the exact
directory for git commit. In order to commit, you will have to add the
new sources first.
If the vendor branch already exists, make sure that you have a local ven-
dor branch which is up to date. To this end, run:
git update-ref refs/heads/vendor/FOO origin/vendor/FOO
The next commands perform the actual import.
git symbolic-ref HEAD refs/heads/vendor/FOO
git add contrib/foo
git commit -m "Import foo-2.3" contrib/foo
With these commands we have imported the vendor sources on their own
branch. In the next step, we merge the vendor branch into master.
git checkout master
git merge vendor/FOO
Now you are free to change the sources in contrib/foo, since you are back
on the master branch. The first thing to do is to add README.DRAGONFLY
and README.DELETED. The former documents how the imported sources can be
obtained, including a checksum of the tarball. The latter lists all
files and directories that have been removed from the source package.
You should use the /usr/src/tools/tools/genreadmedeleted/genreadmedeleted
shell script to generate this file. Commit the READMEs first, then com-
mit your local changes to the sources:
git add contrib/foo/README.D*
git commit -m "foo: add our READMEs"
Finally, push master and the vendor branch to crater:
git push crater master vendor/FOO

SEE ALSO

HISTORY

The development manual page was originally written by Matthew Dillon
<dillon@FreeBSD.org> and first appeared in FreeBSD 5.0, December 2002.
It was rewritten when DragonFly switched to git(1).
DragonFly 4.3 April 2, 2013 DragonFly 4.3