1984263bcSMatthew Dillon.\" 2a63d9f6fSSascha Wildner.\" Copyright (c) 2008 3a63d9f6fSSascha Wildner.\" The DragonFly Project. All rights reserved. 4a63d9f6fSSascha Wildner.\" 5a63d9f6fSSascha Wildner.\" Redistribution and use in source and binary forms, with or without 6a63d9f6fSSascha Wildner.\" modification, are permitted provided that the following conditions 7a63d9f6fSSascha Wildner.\" are met: 8a63d9f6fSSascha Wildner.\" 9a63d9f6fSSascha Wildner.\" 1. Redistributions of source code must retain the above copyright 10a63d9f6fSSascha Wildner.\" notice, this list of conditions and the following disclaimer. 11a63d9f6fSSascha Wildner.\" 2. Redistributions in binary form must reproduce the above copyright 12a63d9f6fSSascha Wildner.\" notice, this list of conditions and the following disclaimer in 13a63d9f6fSSascha Wildner.\" the documentation and/or other materials provided with the 14a63d9f6fSSascha Wildner.\" distribution. 15a63d9f6fSSascha Wildner.\" 3. Neither the name of The DragonFly Project nor the names of its 16a63d9f6fSSascha Wildner.\" contributors may be used to endorse or promote products derived 17a63d9f6fSSascha Wildner.\" from this software without specific, prior written permission. 18a63d9f6fSSascha Wildner.\" 19a63d9f6fSSascha Wildner.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20a63d9f6fSSascha Wildner.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21a63d9f6fSSascha Wildner.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 22a63d9f6fSSascha Wildner.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 23a63d9f6fSSascha Wildner.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 24a63d9f6fSSascha Wildner.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 25a63d9f6fSSascha Wildner.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26a63d9f6fSSascha Wildner.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 27a63d9f6fSSascha Wildner.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28a63d9f6fSSascha Wildner.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 29a63d9f6fSSascha Wildner.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30a63d9f6fSSascha Wildner.\" SUCH DAMAGE. 31a63d9f6fSSascha Wildner.\" 3271bdc883SThomas Nikolajsen.\" $DragonFly: src/share/man/man7/development.7,v 1.12 2008/07/27 22:23:42 thomas Exp $ 33984263bcSMatthew Dillon.\" 34bb60e660SSascha Wildner.Dd August 6, 2009 35984263bcSMatthew Dillon.Dt DEVELOPMENT 7 36984263bcSMatthew Dillon.Os 37984263bcSMatthew Dillon.Sh NAME 38984263bcSMatthew Dillon.Nm development 39a63d9f6fSSascha Wildner.Nd quick starter for development with the DragonFly codebase 40984263bcSMatthew Dillon.Sh DESCRIPTION 418c1a5cc4SThomas Nikolajsen.Dx 42a63d9f6fSSascha Wildneruses the 43a63d9f6fSSascha Wildner.Xr git 1 44a63d9f6fSSascha Wildnerdistributed revision control system. 45a63d9f6fSSascha WildnerIf it is not already on the system, it needs to be installed via 46a63d9f6fSSascha Wildner.Xr pkgsrc 7 47a63d9f6fSSascha Wildner.Pa ( /usr/pkgsrc/devel/scmgit ) . 4895b3720cSHiten Pandya.Pp 4995b3720cSHiten PandyaThe 50a63d9f6fSSascha Wildner.Sx EXAMPLES 51a63d9f6fSSascha Wildnersection gives initial information to get going with development on 52a63d9f6fSSascha Wildner.Dx . 53a63d9f6fSSascha WildnerPlease refer to the 54a63d9f6fSSascha Wildner.Xr git 1 55a63d9f6fSSascha Wildnermanual pages and other related documents for further information on git's 56a63d9f6fSSascha Wildnercapabilities and how to use them. 57e827a42cSSascha WildnerThe 58e827a42cSSascha Wildner.Sx SEE ALSO 59e827a42cSSascha Wildnersection below has some links. 6095b3720cSHiten Pandya.Pp 61a63d9f6fSSascha WildnerFor information on how to build the 62a63d9f6fSSascha Wildner.Dx 63a63d9f6fSSascha Wildnersystem from source code, see 64a63d9f6fSSascha Wildner.Xr build 7 . 6561da8008SSascha WildnerFor information on how to build the LiveCD, LiveDVD or thumb drive image, see 66a63d9f6fSSascha Wildner.Xr release 7 . 67a63d9f6fSSascha Wildner.Sh EXAMPLES 68a63d9f6fSSascha WildnerA fresh copy of the repository can be cloned anywhere. 69a63d9f6fSSascha WildnerNote that the directory to clone into 70a63d9f6fSSascha Wildner.Pa ( /usr/src 71a63d9f6fSSascha Wildnerin the following example) must not exist, so all previous work in this 72a63d9f6fSSascha Wildnerdirectory has to be saved and the directory be removed prior to cloning. 7361da8008SSascha WildnerAlso note that while the main repository is on 7461da8008SSascha Wildner.Pa crater , 7561da8008SSascha Wildnerit is recommended that one of the 7661da8008SSascha Wildner.Dx 7761da8008SSascha Wildnermirrors be used instead. 78a63d9f6fSSascha Wildner.Pp 79e2dbfa0bSThomas NikolajsenSimple setup and updating of local repository is done using 80e2dbfa0bSThomas Nikolajsen.Pa /usr/Makefile : 81e2dbfa0bSThomas Nikolajsen.Bd -literal -offset 4n 82e2dbfa0bSThomas Nikolajsencd /usr 83e2dbfa0bSThomas Nikolajsenmake help # get help 84e2dbfa0bSThomas Nikolajsenmake git-clone # initial setup 85e2dbfa0bSThomas Nikolajsenmake git-update 86e2dbfa0bSThomas Nikolajsen.Ed 87e2dbfa0bSThomas Nikolajsen.Pp 88e2dbfa0bSThomas NikolajsenSomewhat finer control can be achieved using 89e2dbfa0bSThomas Nikolajsen.Xr git 1 9061da8008SSascha Wildnerdirectly. 91a63d9f6fSSascha WildnerTo clone the repository and check out the master branch (this will take 92a63d9f6fSSascha Wildnersome time): 9395b3720cSHiten Pandya.Bd -literal -offset 4n 94a63d9f6fSSascha Wildnercd /usr 95a63d9f6fSSascha Wildnergit clone -o crater git://crater.dragonflybsd.org/dragonfly.git src 96a63d9f6fSSascha Wildnercd src 9795b3720cSHiten Pandya.Ed 9895b3720cSHiten Pandya.Pp 99a63d9f6fSSascha WildnerThe repository can be held up to date by pulling frequently (to set up a 100a63d9f6fSSascha Wildner.Xr cron 8 101a63d9f6fSSascha Wildnerjob, 102a63d9f6fSSascha Wildner.Xr git 1 Ap s 103a63d9f6fSSascha Wildner.Fl Fl git-dir 104a63d9f6fSSascha Wildneroption can be used): 105984263bcSMatthew Dillon.Bd -literal -offset 4n 106984263bcSMatthew Dilloncd /usr/src 107a63d9f6fSSascha Wildnergit pull 108984263bcSMatthew Dillon.Ed 109984263bcSMatthew Dillon.Pp 110a63d9f6fSSascha WildnerIt is not recommended to work directly in the master branch. 111a63d9f6fSSascha WildnerTo create and checkout a working branch: 112a63d9f6fSSascha Wildner.Bd -literal -offset 4n 113a63d9f6fSSascha Wildnergit checkout -b work 114a63d9f6fSSascha Wildner.Ed 115984263bcSMatthew Dillon.Pp 116a63d9f6fSSascha WildnerTo create and checkout a branch of the 117a63d9f6fSSascha Wildner.Dx 2.0 118a63d9f6fSSascha Wildnerrelease (called 119a63d9f6fSSascha Wildner.Sy rel2_0 ) : 120a63d9f6fSSascha Wildner.Bd -literal -offset 4n 121a63d9f6fSSascha Wildnergit checkout -b rel2_0 crater/DragonFly_RELEASE_2_0 122a63d9f6fSSascha Wildner.Ed 123a63d9f6fSSascha Wildner.Pp 124a63d9f6fSSascha WildnerBranches can be deleted just as easy: 125a63d9f6fSSascha Wildner.Bd -literal -offset 4n 126a63d9f6fSSascha Wildnergit branch -d work 127a63d9f6fSSascha Wildner.Ed 128a63d9f6fSSascha Wildner.Pp 129a63d9f6fSSascha WildnerAfter changes have been made to a branch, they can be committed: 130a63d9f6fSSascha Wildner.Bd -literal -offset 4n 131a63d9f6fSSascha Wildnergit commit -a 132a63d9f6fSSascha Wildner.Ed 133a63d9f6fSSascha Wildner.Pp 134a63d9f6fSSascha Wildner.Xr git-commit 1 Ap s 135a63d9f6fSSascha Wildner.Fl m 136a63d9f6fSSascha Wildnerand 137a63d9f6fSSascha Wildner.Fl F 138a63d9f6fSSascha Wildneroptions can be used to specify a commit message on the command line or read 139a63d9f6fSSascha Wildnerit from a file, respectively. 140a63d9f6fSSascha Wildner.Pp 141a63d9f6fSSascha WildnerFinally, branches can be merged with the (updated) master by using 142a63d9f6fSSascha Wildner.Cm rebase : 143a63d9f6fSSascha Wildner.Bd -literal -offset 4n 144a63d9f6fSSascha Wildnergit checkout master 145a63d9f6fSSascha Wildnergit pull 146a63d9f6fSSascha Wildnergit checkout work 147a63d9f6fSSascha Wildnergit rebase master 148a63d9f6fSSascha Wildner.Ed 149c6d6bc19SSimon Schubert.Sh VENDOR IMPORTS 150c6d6bc19SSimon SchubertWhen importing vendor sources, make sure that you don't import 151c6d6bc19SSimon Schuberttoo many unnecessary sources. 152bb60e660SSascha WildnerEspecially test suites that are not used by the 153bb60e660SSascha Wildner.Dx 154bb60e660SSascha Wildnerbuild are good candidates for being stripped away. 155c6d6bc19SSimon SchubertThese instructions assume that you have already extracted 156c6d6bc19SSimon Schubertthe source package into its final directory and that they are 157c6d6bc19SSimon Schuberttrimmed appropriately. 158c6d6bc19SSimon Schubert.Pp 159c6d6bc19SSimon Schubert.Em \&Do not change the vendor sources before importing them 160c6d6bc19SSimon Schuberton the vendor branch! 161c6d6bc19SSimon SchubertNecessary changes to the vendor sources can be applied to 162c6d6bc19SSimon Schubert.Pa master 163c6d6bc19SSimon Schubertafter the import. 164c6d6bc19SSimon Schubert.Pp 165c6d6bc19SSimon SchubertFor the following commands, we will import the imaginary package 166c6d6bc19SSimon Schubert.Nm foo-2.3 167c6d6bc19SSimon Schubertinto 168c6d6bc19SSimon Schubert.Pa /usr/src/contrib/foo . 169c6d6bc19SSimon SchubertIf this is the first import of 170c6d6bc19SSimon Schubert.Nm foo , 171c6d6bc19SSimon Schubertyou will have to choose the name of the vendor branch. 172c6d6bc19SSimon SchubertCustomarily, this will be 173c6d6bc19SSimon Schubert.Pa vendor/FOO . 174c6d6bc19SSimon SchubertHowever, if you intend to maintain multiple vendor sources for the 175c6d6bc19SSimon Schubertsame package 176c6d6bc19SSimon Schubert.Em concurrently , 177c6d6bc19SSimon Schubertyou should choose a branch name which includes part of the version, 178c6d6bc19SSimon Schuberti.e.\& 179c6d6bc19SSimon Schubert.Pa vendor/FOO2 . 180c6d6bc19SSimon Schubert.Pp 181c6d6bc19SSimon SchubertAs a first step, we trick git to work on the vendor branch instead of on 182c6d6bc19SSimon Schubert.Pa master . 183c6d6bc19SSimon SchubertBe careful, since after issuing this command all your commits will go to the 184c6d6bc19SSimon Schubertvendor branch, but you will commit 185c6d6bc19SSimon Schubert.Em the whole working tree 186c6d6bc19SSimon Schubertand not just the vendor sources! 187c6d6bc19SSimon SchubertThus you have to specify the exact directory for 188c6d6bc19SSimon Schubert.Li git commit . 189c6d6bc19SSimon SchubertIn order to commit, you will have to add the new sources first. 190c6d6bc19SSimon Schubert.Bd -literal -offset 4n 191c6d6bc19SSimon Schubertgit symbolic-ref HEAD refs/heads/vendor/FOO 192c6d6bc19SSimon Schubertgit add contrib/foo 193c6d6bc19SSimon Schubertgit commit -m "Import foo-2.3" contrib/foo 194c6d6bc19SSimon Schubert.Ed 195c6d6bc19SSimon Schubert.Pp 196c6d6bc19SSimon SchubertWith these commands we have imported the vendor sources on their own branch. 197c6d6bc19SSimon SchubertIn the next step, we merge the vendor branch into master. 198c6d6bc19SSimon Schubert.Bd -literal -offset 4n 199c6d6bc19SSimon Schubertgit checkout master 200c6d6bc19SSimon Schubertgit merge vendor/FOO 201c6d6bc19SSimon Schubert.Ed 202c6d6bc19SSimon Schubert.Pp 203c6d6bc19SSimon SchubertNow you are free to change the sources in contrib/foo, since you are 204c6d6bc19SSimon Schubertback on the 205c6d6bc19SSimon Schubert.Pa master 206c6d6bc19SSimon Schubertbranch. 207c6d6bc19SSimon SchubertThe first thing to do is to add 208c6d6bc19SSimon Schubert.Pa README.DRAGONFLY 209c6d6bc19SSimon Schubertand 210c6d6bc19SSimon Schubert.Pa README.DELETED . 211c6d6bc19SSimon SchubertThe former documents how the imported sources can be obtained, including 212c6d6bc19SSimon Schuberta checksum of the tarball. 213*1f7cd2b1SMatthias SchmidtThe latter lists all files and directories that have been removed from the 214c6d6bc19SSimon Schubertsource package. 215c6d6bc19SSimon SchubertYou should use the 216c6d6bc19SSimon Schubert.Pa /usr/src/tools/tools/genreadmedeleted/genreadmedeleted 217c6d6bc19SSimon Schubertshell script to generate this file. 218c6d6bc19SSimon SchubertCommit the 219c6d6bc19SSimon Schubert.Pa README Ns s 220c6d6bc19SSimon Schubertfirst, then commit your local changes to the sources: 221c6d6bc19SSimon Schubert.Bd -literal -offset 4n 222c6d6bc19SSimon Schubertgit add contrib/foo/README.D* 223c6d6bc19SSimon Schubertgit commit -m "foo: add our READMEs" 224c6d6bc19SSimon Schubert.Ed 225c6d6bc19SSimon Schubert.Pp 226c6d6bc19SSimon SchubertFinally, push master and the vendor branch to crater: 227c6d6bc19SSimon Schubert.Bd -literal -offset 4n 228c6d6bc19SSimon Schubertgit push crater master vendor/FOO 229c6d6bc19SSimon Schubert.Ed 230984263bcSMatthew Dillon.Sh SEE ALSO 231a63d9f6fSSascha Wildner.Xr git 1 Pq Pa pkgsrc/devel/scmgit , 232984263bcSMatthew Dillon.Xr build 7 , 23371bdc883SThomas Nikolajsen.Xr committer 7 , 234a63d9f6fSSascha Wildner.Xr release 7 235e827a42cSSascha Wildner.Rs 236e827a42cSSascha Wildner.%T "Git User's Manual" 237e827a42cSSascha Wildner.%O "http://www.kernel.org/pub/software/scm/git/docs/user-manual.html" 238e827a42cSSascha Wildner.Re 239e827a42cSSascha Wildner.Rs 240e827a42cSSascha Wildner.%T "Git Magic" 241e827a42cSSascha Wildner.%O "http://www-cs-students.stanford.edu/~blynn/gitmagic/" 242e827a42cSSascha Wildner.Re 243984263bcSMatthew Dillon.Sh HISTORY 244984263bcSMatthew DillonThe 245984263bcSMatthew Dillon.Nm 246984263bcSMatthew Dillonmanual page was originally written by 247984263bcSMatthew Dillon.An Matthew Dillon Aq dillon@FreeBSD.org 248