1 2.\" 3.\" Copyright (c) 2008 4.\" The DragonFly Project. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 3. Neither the name of The DragonFly Project nor the names of its 17.\" contributors may be used to endorse or promote products derived 18.\" from this software without specific, prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" $DragonFly: src/share/man/man7/development.7,v 1.12 2008/07/27 22:23:42 thomas Exp $ 34.\" 35.Dd December 27, 2009 36.Dt DEVELOPMENT 7 37.Os 38.Sh NAME 39.Nm development 40.Nd quick starter for development with the DragonFly codebase 41.Sh DESCRIPTION 42.Dx 43uses the 44.Xr git 1 45distributed revision control system. 46If it is not already on the system, it needs to be installed via 47.Xr pkgsrc 7 48.Pa ( /usr/pkgsrc/devel/scmgit ) . 49.Pp 50The 51.Sx EXAMPLES 52section gives initial information to get going with development on 53.Dx . 54Please refer to the 55.Xr git 1 56manual pages and other related documents for further information on git's 57capabilities and how to use them. 58The 59.Sx SEE ALSO 60section below has some links. 61.Pp 62For information on how to build the 63.Dx 64system from source code, see 65.Xr build 7 . 66For information on how to build the LiveCD, LiveDVD or thumb drive image, see 67.Xr release 7 . 68.Pp 69For a specification of 70.Dx Ap s 71preferred source code style, refer to 72.Xr style 9 . 73An 74.Xr emacs 1 75function to switch C-mode to this style (more or less) can be found in 76.Pa /usr/share/misc/dragonfly.el . 77.Sh EXAMPLES 78A fresh copy of the repository can be cloned anywhere. 79Note that the directory to clone into 80.Pa ( /usr/src 81in the following example) must not exist, so all previous work in this 82directory has to be saved and the directory be removed prior to cloning. 83Also note that while the main repository is on 84.Pa crater , 85it is recommended that one of the 86.Dx 87mirrors be used instead. 88.Pp 89Simple setup and updating of local repository is done using 90.Pa /usr/Makefile : 91.Bd -literal -offset 4n 92cd /usr 93make help # get help 94make src-checkout # initial setup 95make src-update 96.Ed 97.Pp 98Somewhat finer control can be achieved using 99.Xr git 1 100directly. 101To clone the repository and check out the master branch (this will take 102some time): 103.Bd -literal -offset 4n 104cd /usr 105git clone -o crater git://crater.dragonflybsd.org/dragonfly.git src 106cd src 107.Ed 108.Pp 109The repository can be held up to date by pulling frequently (to set up a 110.Xr cron 8 111job, 112.Xr git 1 Ap s 113.Fl Fl git-dir 114option can be used): 115.Bd -literal -offset 4n 116cd /usr/src 117git pull 118.Ed 119.Pp 120It is not recommended to work directly in the master branch. 121To create and checkout a working branch: 122.Bd -literal -offset 4n 123git checkout -b work 124.Ed 125.Pp 126To create and checkout a branch of the 127.Dx 2.0 128release (called 129.Sy rel2_0 ) : 130.Bd -literal -offset 4n 131git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0 132.Ed 133.Pp 134Branches can be deleted just as easy: 135.Bd -literal -offset 4n 136git branch -d work 137.Ed 138.Pp 139After changes have been made to a branch, they can be committed: 140.Bd -literal -offset 4n 141git commit -a 142.Ed 143.Pp 144.Xr git-commit 1 Ap s 145.Fl m 146and 147.Fl F 148options can be used to specify a commit message on the command line or read 149it from a file, respectively. 150.Pp 151Finally, branches can be merged with the (updated) master by using 152.Cm rebase : 153.Bd -literal -offset 4n 154git checkout master 155git pull 156git checkout work 157git rebase master 158.Ed 159.Sh VENDOR IMPORTS 160When importing vendor sources, make sure that you don't import 161too many unnecessary sources. 162Especially test suites that are not used by the 163.Dx 164build are good candidates for being stripped away. 165These instructions assume that you have already extracted 166the source package into its final directory and that they are 167trimmed appropriately. 168.Pp 169.Em \&Do not change the vendor sources before importing them 170on the vendor branch! 171Necessary changes to the vendor sources can be applied to 172.Pa master 173after the import. 174.Pp 175For the following commands, we will import the imaginary package 176.Nm foo-2.3 177into 178.Pa /usr/src/contrib/foo . 179If this is the first import of 180.Nm foo , 181you will have to choose the name of the vendor branch. 182Customarily, this will be 183.Pa vendor/FOO . 184However, if you intend to maintain multiple vendor sources for the 185same package 186.Em concurrently , 187you should choose a branch name which includes part of the version, 188i.e.\& 189.Pa vendor/FOO2 . 190.Pp 191As a first step, we trick git to work on the vendor branch instead of on 192.Pa master . 193Be careful, since after issuing this command all your commits will go to the 194vendor branch, but you will commit 195.Em the whole working tree 196and not just the vendor sources! 197Thus you have to specify the exact directory for 198.Li git commit . 199In order to commit, you will have to add the new sources first. 200.Pp 201If the vendor branch already exists, make sure that you have a local vendor 202branch which is up to date. 203To this end, run: 204.Bd -literal -offset 4n 205git update-ref refs/heads/vendor/FOO origin/vendor/FOO 206.Ed 207.Pp 208The next commands perform the actual import. 209.Bd -literal -offset 4n 210git symbolic-ref HEAD refs/heads/vendor/FOO 211git add contrib/foo 212git commit -m "Import foo-2.3" contrib/foo 213.Ed 214.Pp 215With these commands we have imported the vendor sources on their own branch. 216In the next step, we merge the vendor branch into master. 217.Bd -literal -offset 4n 218git checkout master 219git merge vendor/FOO 220.Ed 221.Pp 222Now you are free to change the sources in contrib/foo, since you are 223back on the 224.Pa master 225branch. 226The first thing to do is to add 227.Pa README.DRAGONFLY 228and 229.Pa README.DELETED . 230The former documents how the imported sources can be obtained, including 231a checksum of the tarball. 232The latter lists all files and directories that have been removed from the 233source package. 234You should use the 235.Pa /usr/src/tools/tools/genreadmedeleted/genreadmedeleted 236shell script to generate this file. 237Commit the 238.Pa README Ns s 239first, then commit your local changes to the sources: 240.Bd -literal -offset 4n 241git add contrib/foo/README.D* 242git commit -m "foo: add our READMEs" 243.Ed 244.Pp 245Finally, push master and the vendor branch to crater: 246.Bd -literal -offset 4n 247git push crater master vendor/FOO 248.Ed 249.Sh SEE ALSO 250.Xr git 1 Pq Pa pkgsrc/devel/scmgit , 251.Xr build 7 , 252.Xr committer 7 , 253.Xr release 7 254.Rs 255.%T "Git User's Manual" 256.%O "http://www.kernel.org/pub/software/scm/git/docs/user-manual.html" 257.Re 258.Rs 259.%T "Git Magic" 260.%O "http://www-cs-students.stanford.edu/~blynn/gitmagic/" 261.Re 262.Sh HISTORY 263The 264.Nm 265manual page was originally written by 266.An Matthew Dillon Aq dillon@FreeBSD.org 267and first appeared 268in 269.Fx 5.0 , 270December 2002. 271It was rewritten when 272.Dx 273switched to 274.Xr git 1 . 275