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.Dd April 2, 2013 33.Dt DEVELOPMENT 7 34.Os 35.Sh NAME 36.Nm development 37.Nd quick starter for development with the DragonFly codebase 38.Sh DESCRIPTION 39.Dx 40uses the 41.Xr git 1 42distributed revision control system. 43If it is not already on the system, it needs to be installed via 44.Xr dports 7 45.Pa ( devel/git ) . 46.Pp 47The 48.Sx EXAMPLES 49section gives initial information to get going with development on 50.Dx . 51Please refer to the 52.Xr git 1 53manual pages and other related documents for further information on git's 54capabilities and how to use them. 55The 56.Sx SEE ALSO 57section below has some links. 58.Pp 59For information on how to build the 60.Dx 61system from source code, see 62.Xr build 7 . 63For information on how to build the LiveCD, LiveDVD or thumb drive image, see 64.Xr release 7 . 65.Pp 66For a specification of 67.Dx Ap s 68preferred source code style, refer to 69.Xr style 9 . 70An 71.Xr emacs 1 72function to switch C-mode to this style (more or less) can be found in 73.Pa /usr/share/misc/dragonfly.el . 74For 75.Xr vim 1 76users, a 77.Pa /usr/share/misc/dragonfly.vim 78is available. 79.Sh EXAMPLES 80A fresh copy of the repository can be cloned anywhere. 81Note that the directory to clone into 82.Pa ( /usr/src 83in the following example) must not exist, so all previous work in this 84directory has to be saved and the directory be removed prior to cloning. 85Also note that while the main repository is on 86.Pa crater , 87it is recommended that one of the 88.Dx 89mirrors be used instead. 90.Pp 91Simple setup and updating of local repository is done using 92.Pa /usr/Makefile : 93.Bd -literal -offset 4n 94cd /usr 95make help # get help 96make src-checkout # initial setup 97make src-update 98.Ed 99.Pp 100Somewhat finer control can be achieved using 101.Xr git 1 102directly. 103To clone the repository and check out the master branch (this will take 104some time): 105.Bd -literal -offset 4n 106cd /usr 107git clone -o crater git://crater.dragonflybsd.org/dragonfly.git src 108cd src 109.Ed 110.Pp 111The repository can be held up to date by pulling frequently (to set up a 112.Xr cron 8 113job, 114.Xr git 1 Ap s 115.Fl Fl git-dir 116option can be used): 117.Bd -literal -offset 4n 118cd /usr/src 119git pull 120.Ed 121.Pp 122It is not recommended to work directly in the master branch. 123To create and checkout a working branch: 124.Bd -literal -offset 4n 125git checkout -b work 126.Ed 127.Pp 128To create and checkout a branch of the 129.Dx 2.0 130release (called 131.Sy rel2_0 ) : 132.Bd -literal -offset 4n 133git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0 134.Ed 135.Pp 136Branches can be deleted just as easy: 137.Bd -literal -offset 4n 138git branch -d work 139.Ed 140.Pp 141After changes have been made to a branch, they can be committed: 142.Bd -literal -offset 4n 143git commit -a 144.Ed 145.Pp 146.Xr git-commit 1 Ap s 147.Fl m 148and 149.Fl F 150options can be used to specify a commit message on the command line or read 151it from a file, respectively. 152.Pp 153Finally, branches can be merged with the (updated) master by using 154.Cm rebase : 155.Bd -literal -offset 4n 156git checkout master 157git pull 158git checkout work 159git rebase master 160.Ed 161.Sh VENDOR IMPORTS 162When importing vendor sources, make sure that you don't import 163too many unnecessary sources. 164Especially test suites that are not used by the 165.Dx 166build are good candidates for being stripped away. 167These instructions assume that you have already extracted 168the source package into its final directory and that they are 169trimmed appropriately. 170.Pp 171.Em \&Do not change the vendor sources before importing them 172on the vendor branch! 173Necessary changes to the vendor sources can be applied to 174.Pa master 175after the import. 176.Pp 177For the following commands, we will import the imaginary package 178.Nm foo-2.3 179into 180.Pa /usr/src/contrib/foo . 181If this is the first import of 182.Nm foo , 183you will have to choose the name of the vendor branch. 184Customarily, this will be 185.Pa vendor/FOO . 186However, if you intend to maintain multiple vendor sources for the 187same package 188.Em concurrently , 189you should choose a branch name which includes part of the version, 190i.e.\& 191.Pa vendor/FOO2 . 192.Pp 193As a first step, we trick git to work on the vendor branch instead of on 194.Pa master . 195Be careful, since after issuing this command all your commits will go to the 196vendor branch, but you will commit 197.Em the whole working tree 198and not just the vendor sources! 199Thus you have to specify the exact directory for 200.Li git commit . 201In order to commit, you will have to add the new sources first. 202.Pp 203If the vendor branch already exists, make sure that you have a local vendor 204branch which is up to date. 205To this end, run: 206.Bd -literal -offset 4n 207git update-ref refs/heads/vendor/FOO origin/vendor/FOO 208.Ed 209.Pp 210The next commands perform the actual import. 211.Bd -literal -offset 4n 212git symbolic-ref HEAD refs/heads/vendor/FOO 213git add contrib/foo 214git commit -m "Import foo-2.3" contrib/foo 215.Ed 216.Pp 217With these commands we have imported the vendor sources on their own branch. 218In the next step, we merge the vendor branch into master. 219.Bd -literal -offset 4n 220git checkout master 221git merge vendor/FOO 222.Ed 223.Pp 224Now you are free to change the sources in contrib/foo, since you are 225back on the 226.Pa master 227branch. 228The first thing to do is to add 229.Pa README.DRAGONFLY 230and 231.Pa README.DELETED . 232The former documents how the imported sources can be obtained, including 233a checksum of the tarball. 234The latter lists all files and directories that have been removed from the 235source package. 236You should use the 237.Pa /usr/src/tools/tools/genreadmedeleted/genreadmedeleted 238shell script to generate this file. 239Commit the 240.Pa README Ns s 241first, then commit your local changes to the sources: 242.Bd -literal -offset 4n 243git add contrib/foo/README.D* 244git commit -m "foo: add our READMEs" 245.Ed 246.Pp 247Finally, push master and the vendor branch to crater: 248.Bd -literal -offset 4n 249git push crater master vendor/FOO 250.Ed 251.Sh SEE ALSO 252.Xr git 1 Pq Pa devel/git , 253.Xr build 7 , 254.Xr committer 7 , 255.Xr release 7 256.Rs 257.%T "Documentation on git's page" 258.%O "http://git-scm.com/documentation" 259.Re 260.Rs 261.%T "Git Magic" 262.%O "http://www-cs-students.stanford.edu/~blynn/gitmagic/" 263.Re 264.Sh HISTORY 265The 266.Nm 267manual page was originally written by 268.An Matthew Dillon Aq Mt dillon@FreeBSD.org 269and first appeared 270in 271.Fx 5.0 , 272December 2002. 273It was rewritten when 274.Dx 275switched to 276.Xr git 1 . 277