205 lines
5.6 KiB
Groff
205 lines
5.6 KiB
Groff
.\" Copyright (c) 2018 Edward Tomasz Napierala <trasz@FreeBSD.org>
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd March 19, 2021
|
|
.Dt DEVELOPMENT 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm development
|
|
.Nd introduction to
|
|
.Fx
|
|
development process
|
|
.Sh DESCRIPTION
|
|
.Fx
|
|
development is split into three major suprojects: doc, ports, and src.
|
|
Doc is the documentation, such as the
|
|
.Fx
|
|
Handbook.
|
|
To read more, see:
|
|
.Pp
|
|
.Lk https://www.FreeBSD.org/doc/en/books/fdp-primer/
|
|
.Pp
|
|
Ports, described further in
|
|
.Xr ports 7 ,
|
|
are the way to build, package, and install third party software.
|
|
To read more, see:
|
|
.Pp
|
|
.Lk https://www.FreeBSD.org/doc/en/books/porters-handbook/
|
|
.Pp
|
|
The last one, src, revolves around the source code for the base system,
|
|
consisting of the kernel, and the libraries and utilities commonly called
|
|
the world.
|
|
.Pp
|
|
The Committer's Guide, describing topics relevant to all committers,
|
|
can be found at:
|
|
.Pp
|
|
.Lk https://www.FreeBSD.org/doc/en/articles/committers-guide/
|
|
.Pp
|
|
.Fx
|
|
src development takes place in the project-hosted
|
|
Git repository, located at:
|
|
.Pp
|
|
.Lk https://git.FreeBSD.org/src.git
|
|
.Pp
|
|
The push URL is:
|
|
.Pp
|
|
.Lk ssh://git@gitrepo.FreeBSD.org/src.git
|
|
.Pp
|
|
There is also a list of public, read-only Git mirrors at:
|
|
.Pp
|
|
.Lk https://docs.freebsd.org/en/books/handbook/mirrors/#external-mirrors
|
|
.Pp
|
|
The
|
|
.Ql main
|
|
Git branch represents CURRENT;
|
|
all changes are first committed to CURRENT and then usually cherry-picked
|
|
back to STABLE, which refers to Git branches such as
|
|
.Ql stable/13 .
|
|
Every few years a new STABLE is branched from CURRENT,
|
|
with an incremented major version number.
|
|
Releases are then branched off STABLE and numbered with consecutive minor
|
|
numbers.
|
|
.Pp
|
|
Layout of the source tree is described in
|
|
.Xr hier 7 .
|
|
Build instructions can be found in
|
|
.Xr build 7
|
|
and
|
|
.Xr release 7 .
|
|
Kernel programming interfaces (KPIs) are documented in section 9
|
|
manual pages; use
|
|
.Ql "apropos -s 9 ."
|
|
for a list.
|
|
Regression test suite is described in
|
|
.Xr tests 7 .
|
|
For coding conventions, see
|
|
.Xr style 9 .
|
|
.Pp
|
|
To ask questions regarding development, use the mailing lists,
|
|
such as freebsd-arch@ and freebsd-hackers@:
|
|
.Pp
|
|
.Lk https://lists.FreeBSD.org
|
|
.Pp
|
|
To get your patches integrated into the main
|
|
.Fx
|
|
repository use Phabricator;
|
|
it is a code review tool that allows other developers to review the changes,
|
|
suggest improvements, and, eventually, allows them to pick up the change and
|
|
commit it:
|
|
.Pp
|
|
.Lk https://reviews.FreeBSD.org
|
|
.Pp
|
|
To check the latest
|
|
.Fx
|
|
build and test status of CURRENT and STABLE branches,
|
|
the continuous integration system is at:
|
|
.Pp
|
|
.Lk https://ci.FreeBSD.org
|
|
.Pp
|
|
.Sh EXAMPLES
|
|
Check out the CURRENT branch, build it, and install, overwriting the current
|
|
system:
|
|
.Bd -literal -offset indent
|
|
git clone https://git.FreeBSD.org/src.git src
|
|
cd src
|
|
make -sj8 buildworld buildkernel installkernel
|
|
shutdown -r now
|
|
.Ed
|
|
.Pp
|
|
After reboot:
|
|
.Bd -literal -offset indent
|
|
cd src
|
|
make -j8 installworld
|
|
reboot
|
|
.Ed
|
|
.Pp
|
|
Rebuild and reinstall a single piece of userspace, in this
|
|
case
|
|
.Xr ls 1 :
|
|
.Bd -literal -offset indent
|
|
cd src/bin/ls
|
|
make clean all install
|
|
.Ed
|
|
.Pp
|
|
Quickly rebuild and reinstall the kernel, only recompiling the files
|
|
changed since last build; note that this will only work if the full kernel
|
|
build has been completed in the past, not on a fresh source tree:
|
|
.Bd -literal -offset indent
|
|
cd src
|
|
make -sj8 kernel KERNFAST=1
|
|
.Ed
|
|
.Pp
|
|
To rebuild parts of
|
|
.Fx
|
|
for another CPU architecture,
|
|
first prepare your source tree by building the cross-toolchain:
|
|
.Bd -literal -offset indent
|
|
cd src
|
|
make -sj8 toolchain TARGET_ARCH=armv6
|
|
.Ed
|
|
.Pp
|
|
Afterwards, to build and install a single piece of userspace, use:
|
|
.Bd -literal -offset indent
|
|
cd src/bin/ls
|
|
make buildenv TARGET_ARCH=armv6
|
|
make clean all install DESTDIR=/clients/arm
|
|
.Ed
|
|
.Pp
|
|
Likewise, to quickly rebuild and reinstall the kernel, use:
|
|
.Bd -literal -offset indent
|
|
cd src
|
|
make buildenv TARGET_ARCH=armv6
|
|
make -sj8 kernel KERNFAST=1 DESTDIR=/clients/arm
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr git 1 ,
|
|
.Xr witness 4 ,
|
|
.Xr build 7 ,
|
|
.Xr hier 7 ,
|
|
.Xr ports 7 ,
|
|
.Xr release 7 ,
|
|
.Xr tests 7 ,
|
|
.Xr locking 9 ,
|
|
.Xr style 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
manual page was originally written by
|
|
.An Matthew Dillon Aq Mt dillon@FreeBSD.org
|
|
and first appeared
|
|
in
|
|
.Fx 5.0 ,
|
|
December 2002.
|
|
It was since extensively modified by
|
|
.An Eitan Adler Aq Mt eadler@FreeBSD.org
|
|
to reflect the repository conversion from
|
|
.Xr cvs 1
|
|
to
|
|
.Xr svn 1 .
|
|
It was rewritten from scratch by
|
|
.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
|
|
for
|
|
.Fx 12.0 .
|