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 August 19, 2020 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 suprojects: doc, ports, and src. 37Doc is the documentation, such as the 38.Fx 39Handbook. 40To read more, see: 41.Pp 42.Lk https://www.FreeBSD.org/doc/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://www.FreeBSD.org/doc/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://www.FreeBSD.org/doc/en/articles/committers-guide/ 59.Pp 60.Fx 61src development takes place in the CURRENT branch in Subversion, 62located at: 63.Pp 64.Lk https://svn.FreeBSD.org/base/head 65.Pp 66There is also a read-only GitHub mirror at: 67.Pp 68.Lk https://github.com/freebsd/freebsd 69.Pp 70Changes are first committed to CURRENT and then usually merged back 71to STABLE. 72Every few years the CURRENT branch is renamed to STABLE, and a new 73CURRENT is branched, with an incremented major version number. 74Releases are then branched off STABLE and numbered with consecutive minor 75numbers. 76.Pp 77Layout of the source tree is described in 78.Xr hier 7 . 79Build instructions can be found in 80.Xr build 7 81and 82.Xr release 7 . 83Kernel programming interfaces (KPIs) are documented in section 9 84manual pages; use 85.Ql "apropos -s 9 ." 86for a list. 87Regression test suite is described in 88.Xr tests 7 . 89For coding conventions, see 90.Xr style 9 . 91.Pp 92To ask questions regarding development, use the mailing lists, 93such as freebsd-arch@ and freebsd-hackers@: 94.Pp 95.Lk https://lists.FreeBSD.org 96.Pp 97To get your patches integrated into the main 98.Fx 99repository use Phabricator; 100it is a code review tool that allows other developers to review the changes, 101suggest improvements, and, eventually, allows them to pick up the change and 102commit it: 103.Pp 104.Lk https://reviews.FreeBSD.org 105.Pp 106To check the latest 107.Fx 108build and test status of CURRENT and STABLE branches, 109the continuous integration system is at: 110.Pp 111.Lk https://ci.FreeBSD.org 112.Pp 113.Sh EXAMPLES 114Check out the CURRENT branch, build it, and install, overwriting the current 115system: 116.Bd -literal -offset indent 117svnlite co https://svn.FreeBSD.org/base/head src 118cd src 119make -sj8 buildworld buildkernel installkernel 120shutdown -r now 121.Ed 122.Pp 123After reboot: 124.Bd -literal -offset indent 125cd src 126make -j8 installworld 127reboot 128.Ed 129.Pp 130Rebuild and reinstall a single piece of userspace, in this 131case 132.Xr ls 1 : 133.Bd -literal -offset indent 134cd src/bin/ls 135make clean all install 136.Ed 137.Pp 138Quickly rebuild and reinstall the kernel, only recompiling the files 139changed since last build; note that this will only work if the full kernel 140build has been completed in the past, not on a fresh source tree: 141.Bd -literal -offset indent 142cd src 143make -sj8 kernel KERNFAST=1 144.Ed 145.Pp 146To rebuild parts of 147.Fx 148for another CPU architecture, 149first prepare your source tree by building the cross-toolchain: 150.Bd -literal -offset indent 151cd src 152make -sj8 toolchain TARGET_ARCH=armv6 153.Ed 154.Pp 155Afterwards, to build and install a single piece of userspace, use: 156.Bd -literal -offset indent 157cd src/bin/ls 158make buildenv TARGET_ARCH=armv6 159make clean all install DESTDIR=/clients/arm 160.Ed 161.Pp 162Likewise, to quickly rebuild and reinstall the kernel, use: 163.Bd -literal -offset indent 164cd src 165make buildenv TARGET_ARCH=armv6 166make -sj8 kernel KERNFAST=1 DESTDIR=/clients/arm 167.Ed 168.Sh SEE ALSO 169.Xr svnlite 1 , 170.Xr witness 4 , 171.Xr build 7 , 172.Xr hier 7 , 173.Xr ports 7 , 174.Xr release 7 , 175.Xr tests 7 , 176.Xr locking 9 , 177.Xr style 9 178.Sh HISTORY 179The 180.Nm 181manual page was originally written by 182.An Matthew Dillon Aq Mt dillon@FreeBSD.org 183and first appeared 184in 185.Fx 5.0 , 186December 2002. 187It was since extensively modified by 188.An Eitan Adler Aq Mt eadler@FreeBSD.org 189to reflect the repository conversion from 190.Xr cvs 1 191to 192.Xr svn 1 . 193It was rewritten from scratch by 194.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org 195for 196.Fx 12.0 . 197