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 March 3, 2020 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 of the local repository is done using 92.Pa /usr/Makefile : 93.Bd -literal -offset 4n 94cd /usr 95make help # get brief help 96make src-create # create the source repository 97.Ed 98.Pp 99Somewhat finer control can be achieved using 100.Xr git 1 101directly. 102To clone the repository and check out the master branch (this will take 103some time): 104.Bd -literal -offset 4n 105cd /usr 106git clone -o crater git://crater.dragonflybsd.org/dragonfly.git src 107cd src 108.Ed 109.Pp 110The repository can be held up to date by pulling frequently (to set up a 111.Xr cron 8 112job, 113.Xr git 1 Ap s 114.Fl Fl git-dir 115option can be used): 116.Bd -literal -offset 4n 117cd /usr/src 118git pull 119.Ed 120.Pp 121It is not recommended to work directly in the master branch. 122To create and checkout a working branch: 123.Bd -literal -offset 4n 124git checkout -b work 125.Ed 126.Pp 127To create and checkout a branch of the 128.Dx 2.0 129release (called 130.Sy rel2_0 ) : 131.Bd -literal -offset 4n 132git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0 133.Ed 134.Pp 135Branches can be deleted just as easy: 136.Bd -literal -offset 4n 137git branch -d work 138.Ed 139.Pp 140After changes have been made to a branch, they can be committed: 141.Bd -literal -offset 4n 142git commit -a 143.Ed 144.Pp 145.Xr git-commit 1 Ap s 146.Fl m 147and 148.Fl F 149options can be used to specify a commit message on the command line or read 150it from a file, respectively. 151.Pp 152Finally, branches can be merged with the (updated) master by using 153.Cm rebase : 154.Bd -literal -offset 4n 155git checkout master 156git pull 157git checkout work 158git rebase master 159.Ed 160.Sh VENDOR IMPORTS 161When importing vendor sources, make sure that you don't import 162too many unnecessary sources. 163Especially test suites that are not used by the 164.Dx 165build are good candidates for being stripped away. 166These instructions assume that you have already extracted 167the source package into its final directory and trimmed the source 168files appropriately. 169.Pp 170.Em \&Do not change the vendor sources before importing them 171on the vendor branch! 172Necessary changes to the vendor sources should be applied to the 173.Pa master 174branch after the import. 175.Pp 176For the following example, we will import the imaginary package 177.Nm foo-2.3 178into 179.Pa contrib/foo . 180If this is the first import of 181.Nm foo , 182you will have to choose the name of the vendor branch. 183Customarily, this will be 184.Pa vendor/FOO . 185However, if you intend to maintain multiple vendor sources for the 186same package 187.Em concurrently , 188you should choose a branch name that includes part of the version, e.g., 189.Pa vendor/FOO2 . 190.Pp 191First, we need to create an orphan branch (i.e., a new branch with no 192history) as the vendor branch: 193.Bd -literal -offset 4n 194git checkout --orphan vendor/FOO 195.Ed 196.Pp 197Then we remove the previous content because the vendor branch will only 198contain the vendor sources to be imported: 199.Bd -literal -offset 4n 200git rm -rf . 201.Ed 202.Pp 203Next, move the prepared vendor sources to the destination, i.e., 204.Pa contrib/foo . 205Then we perform the import: 206.Bd -literal -offset 4n 207git add contrib/foo 208git commit -m "Import foo-2.3 on the vendor branch" 209.Ed 210.Pp 211Next, we merge the vendor branch into 212.Pa master : 213.Bd -literal -offset 4n 214git checkout master 215git merge --allow-unrelated-histories vendor/FOO 216.Ed 217.Pp 218Now you are free to change the sources in 219.Pa contrib/foo , 220since you are back to the 221.Pa master 222branch. 223The first thing to do is to add 224.Pa README.DRAGONFLY 225and 226.Pa README.DELETED . 227The former documents how the imported sources can be obtained, including 228basic information (e.g., version, date, checksum) of the source package. 229The latter lists all files and directories that have been removed from the 230source package. 231You should use the 232.Pa /usr/src/tools/tools/genreadmedeleted/genreadmedeleted 233shell script to generate this file. 234Commit the 235.Pa README Ns s 236first: 237.Bd -literal -offset 4n 238git add contrib/foo/README.D* 239git commit -m "foo: add our READMEs" 240.Ed 241.Pp 242And then commit your local changes to the sources. 243Finally, push 244.Pa master 245and the vendor branch to the upstream: 246.Bd -literal -offset 4n 247git push crater master vendor/FOO 248.Ed 249.Sh SEE ALSO 250.Xr git 1 Pq Pa devel/git , 251.Xr build 7 , 252.Xr committer 7 , 253.Xr release 7 254.Rs 255.%T "Documentation on git's page" 256.%O "http://git-scm.com/documentation" 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 Mt 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