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