xref: /freebsd/share/man/man7/development.7 (revision 058ac3e8063366dafa634d9107642e12b038bf09)
1.\" Copyright (c) 2018 Edward Tomasz Napierala <trasz@FreeBSD.org>
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\"    notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\"    notice, this list of conditions and the following disclaimer in the
10.\"    documentation and/or other materials provided with the distribution.
11.\"
12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
22.\" SUCH DAMAGE.
23.\"
24.\" $FreeBSD$
25.\"
26.Dd November 1, 2022
27.Dt DEVELOPMENT 7
28.Os
29.Sh NAME
30.Nm development
31.Nd introduction to
32.Fx
33development process
34.Sh DESCRIPTION
35.Fx
36development is split into three major subprojects: doc, ports, and src.
37Doc is the documentation, such as the
38.Fx
39Handbook.
40To read more, see:
41.Pp
42.Lk https://docs.FreeBSD.org/en/books/fdp-primer/
43.Pp
44Ports, described further in
45.Xr ports 7 ,
46are the way to build, package, and install third party software.
47To read more, see:
48.Pp
49.Lk https://docs.FreeBSD.org/en/books/porters-handbook/
50.Pp
51The last one, src, revolves around the source code for the base system,
52consisting of the kernel, and the libraries and utilities commonly called
53the world.
54.Pp
55The Committer's Guide, describing topics relevant to all committers,
56can be found at:
57.Pp
58.Lk https://docs.freebsd.org/en/articles/committers-guide/
59.Pp
60.Fx
61src development takes place in the project-hosted
62Git repository, located at:
63.Pp
64.Lk https://git.FreeBSD.org/src.git
65.Pp
66The push URL is:
67.Pp
68.Lk ssh://git@gitrepo.FreeBSD.org/src.git
69.Pp
70There is also a list of public, read-only Git mirrors at:
71.Pp
72.Lk https://docs.FreeBSD.org/en/books/handbook/mirrors/#external-mirrors
73.Pp
74The
75.Ql main
76Git branch represents CURRENT;
77all changes are first committed to CURRENT and then usually cherry-picked
78back to STABLE, which refers to Git branches such as
79.Ql stable/13 .
80Every few years a new STABLE is branched from CURRENT,
81with an incremented major version number.
82Releases are then branched off STABLE and numbered with consecutive minor
83numbers.
84.Pp
85The layout of the source tree is described in its
86.Pa README.md
87file.
88Build instructions can be found in
89.Xr build 7
90and
91.Xr release 7 .
92Kernel programming interfaces (KPIs) are documented in section 9
93manual pages; use
94.Ql "apropos -s 9 ."
95for a list.
96Regression test suite is described in
97.Xr tests 7 .
98For coding conventions, see
99.Xr style 9 .
100.Pp
101To ask questions regarding development, use the mailing lists,
102such as freebsd-arch@ and freebsd-hackers@:
103.Pp
104.Lk https://lists.FreeBSD.org
105.Pp
106To get your patches integrated into the main
107.Fx
108repository use Phabricator;
109it is a code review tool that allows other developers to review the changes,
110suggest improvements, and, eventually, allows them to pick up the change and
111commit it:
112.Pp
113.Lk https://reviews.FreeBSD.org
114.Pp
115To check the latest
116.Fx
117build and test status of CURRENT and STABLE branches,
118the continuous integration system is at:
119.Pp
120.Lk https://ci.FreeBSD.org
121.Pp
122.Sh EXAMPLES
123Check out the CURRENT branch, build it, and install, overwriting the current
124system:
125.Bd -literal -offset indent
126git clone https://git.FreeBSD.org/src.git src
127cd src
128make -sj8 buildworld buildkernel installkernel
129shutdown -r now
130.Ed
131.Pp
132After reboot:
133.Bd -literal -offset indent
134cd src
135make -j8 installworld
136reboot
137.Ed
138.Pp
139Rebuild and reinstall a single piece of userspace, in this
140case
141.Xr ls 1 :
142.Bd -literal -offset indent
143cd src/bin/ls
144make clean all install
145.Ed
146.Pp
147Quickly rebuild and reinstall the kernel, only recompiling the files
148changed since last build; note that this will only work if the full kernel
149build has been completed in the past, not on a fresh source tree:
150.Bd -literal -offset indent
151cd src
152make -sj8 kernel KERNFAST=1
153.Ed
154.Pp
155To rebuild parts of
156.Fx
157for another CPU architecture,
158first prepare your source tree by building the cross-toolchain:
159.Bd -literal -offset indent
160cd src
161make -sj8 toolchain TARGET_ARCH=aarch64
162.Ed
163.Pp
164Afterwards, to build and install a single piece of userspace, use:
165.Bd -literal -offset indent
166cd src/bin/ls
167make buildenv TARGET_ARCH=aarch64
168make clean all install DESTDIR=/clients/arm
169.Ed
170.Pp
171Likewise, to quickly rebuild and reinstall the kernel, use:
172.Bd -literal -offset indent
173cd src
174make buildenv TARGET_ARCH=aarch64
175make -sj8 kernel KERNFAST=1 DESTDIR=/clients/arm
176.Ed
177.Sh SEE ALSO
178.Xr git 1 ,
179.Xr witness 4 ,
180.Xr build 7 ,
181.Xr hier 7 ,
182.Xr ports 7 ,
183.Xr release 7 ,
184.Xr tests 7 ,
185.Xr locking 9 ,
186.Xr style 9
187.Sh HISTORY
188The
189.Nm
190manual page was originally written by
191.An Matthew Dillon Aq Mt dillon@FreeBSD.org
192and first appeared
193in
194.Fx 5.0 ,
195December 2002.
196It was since extensively modified by
197.An Eitan Adler Aq Mt eadler@FreeBSD.org
198to reflect the repository conversion from
199.Lk https://www.nongnu.org/cvs/ CVS
200to
201.Lk https://subversion.apache.org/ Subversion .
202It was rewritten from scratch by
203.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
204for
205.Fx 12.0 .
206