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