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