Index: stable/11/share/man/man7/development.7 =================================================================== --- stable/11/share/man/man7/development.7 (revision 366235) +++ stable/11/share/man/man7/development.7 (revision 366236) @@ -1,480 +1,481 @@ .\" Copyright (C) 1998 Matthew Dillon. All rights reserved. .\" .\" 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 AUTHOR 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 AUTHOR 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 7, 2013 +.Dd August 19, 2020 .Dt DEVELOPMENT 7 .Os .Sh NAME .Nm development .Nd "introduction to development with the FreeBSD codebase" .Sh DESCRIPTION This manual page describes how an ordinary system operator, .Ux administrator, or developer can, without any special permission, obtain, maintain, and modify the .Fx codebase as well as how to maintain a master build which can then be exported to other machines in your network. This manual page is targeted to system operators, programmers, and developers. .Pp Please note that what is being described here is based on a complete .Fx environment, not just the .Fx kernel. The methods described here are as applicable to production installations as it is to development environments. .Sh SETTING UP THE ENVIRONMENT ON THE MASTER SERVER Your master server should always run a stable, production version of the .Fx operating system. This does not prevent you from doing -CURRENT builds or development. The last thing you want to do is to run an unstable environment on your master server which could lead to a situation where you lose the environment and/or cannot recover from a mistake. .Pp Create a partition called .Pa /FreeBSD . Approximately 20GB is recommended. This partition will contain nearly all the development environment, including the subversion tree, broken-out source, and possibly even object files. You are going to export this partition to your other machines via a READ-ONLY NFS export so do not mix it with other more security-sensitive partitions. .Pp You have to make a choice in regards to .Pa /usr/obj . You can put .Pa /usr/obj in .Pa /FreeBSD or you can make .Pa /usr/obj its own partition. I recommend making it a separate partition for several reasons. First, as a safety measure since this partition is written to a great deal. Second, because you typically do not have to back it up. Third, because it makes it far easier to mix and match the development environments which are described later in this document. I recommend a .Pa /usr/obj partition of at least 12GB. .Pp On the master server, use .Xr svn 1 to pull down and maintain the .Fx source. The first pull will take a long time, it is several gigabytes, but once you have it, the updates will be quite small. Run all .Xr svn 1 operations as .Dq Li root .Pp Keeping the broken-out source and ports in .Pa /FreeBSD allows you to export it to other machines via read-only NFS. This also means you only need to edit/maintain files in one place and all your clients automatically pick up the changes. .Bd -literal -offset 4n mkdir /FreeBSD cd /FreeBSD svn co https://svn.freebsd.org/ports/head ports svn co https://svn.freebsd.org/doc/head doc svn co https://svn.freebsd.org/base/head src cd /usr rm -rf src ln -s /FreeBSD/src src .Ed .Pp Note that exporting .Pa /usr/obj via read-only NFS to your other boxes will allow you to build on your main server and install from your other boxes. If you also want to do builds on some or all of the clients you can simply have .Pa /usr/obj be a local directory on those clients. You should never export .Pa /usr/obj read-write, it will lead to all sorts of problems and issues down the line and presents a security problem as well. It is far easier to do builds on the master server and then only do installs on the clients. .Pp I usually maintain my ports tree via svn or portsnap. With some fancy softlinks you can make the ports tree available both on your master server and on all of your other machines. Note that the ports tree exists only on the HEAD ports branch, so its always usable even on a -STABLE box. This is what you do: .Bd -literal -offset 4n (THESE COMMANDS ON THE MASTER SERVER AND ON ALL CLIENTS) cd /usr rm -rf ports ln -s /FreeBSD/ports ports cd /usr/ports (this pushes into the softlink) rm -rf distfiles (ON MASTER SERVER ONLY) ln -s /usr/ports.distfiles distfiles (ON MASTER SERVER ONLY) mkdir /usr/ports.distfiles mkdir /usr/ports.workdir .Ed .Pp Since .Pa /usr/ports is softlinked into what will be read-only on all of your clients, you have to tell the ports system to use a different working directory to hold ports builds. You want to add a line to your .Xr make.conf 5 file on the master server and on all your clients: .Bd -literal -offset 4n WRKDIRPREFIX=/usr/ports.workdir .Ed .Pp You should try to make the directory you use for the ports working directory as well as the directory used to hold distfiles consistent across all of your machines. If there is not enough room in .Pa /usr/ports.distfiles and .Pa /usr/ports.workdir I usually make those softlinks (since this is on .Pa /usr these are per-machine) to where the distfiles and working space really are. .Sh EXPORTING VIA NFS FROM THE MASTER SERVER The master server needs to export .Pa /FreeBSD and .Pa /usr/obj via NFS so all the rest of your machines can get at them. I strongly recommend using a read-only export for both security and safety. The environment I am describing in this manual page is designed primarily around read-only NFS exports. Your exports file on the master server should contain the following lines: .Bd -literal -offset 4n /FreeBSD -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK /usr/obj -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK .Ed .Pp Of course, NFS server operations must also be configured on that machine. This is typically done via your .Pa /etc/rc.conf : .Bd -literal -offset 4n nfs_server_enable="YES" nfs_server_flags="-u -t -n 4" .Ed .Sh THE CLIENT ENVIRONMENT All of your client machines can import the development/build environment directory simply by NFS mounting .Pa /FreeBSD and .Pa /usr/obj from the master server. A typical .Pa /etc/fstab entry on your client machines will be something like this: .Bd -literal -offset 4n masterserver:/FreeBSD /FreeBSD nfs ro,bg 0 0 masterserver:/usr/obj /usr/obj nfs ro,bg 0 0 .Ed .Pp And, of course, you should configure the client for NFS client operations via .Pa /etc/rc.conf . In particular, this will turn on .Xr nfsiod 8 which will improve client-side NFS performance: .Bd -literal -offset 4n nfs_client_enable="YES" .Ed .Pp Each client should create softlinks for .Pa /usr/ports and .Pa /usr/src that point into the NFS-mounted environment. If a particular client is running -CURRENT, .Pa /usr/src should be a softlink to .Pa /FreeBSD/src . If it is running -STABLE, .Pa /usr/src should be a softlink to .Pa /FreeBSD/FreeBSD-4.x/src . I do not usually create a .Pa /usr/src2 softlink on clients, that is used as a convenient shortcut when working on the source code on the master server only and could create massive confusion (of the human variety) on a client. .Bd -literal -offset 4n (ON EACH CLIENT) cd /usr rm -rf ports src ln -s /FreeBSD/ports ports ln -s /FreeBSD/src src .Ed .Pp Do not forget to create the working directories so you can build ports, as previously described. If these are not good locations, make them softlinks to the correct location. Remember that .Pa /usr/ports/distfiles is exported by the master server and is therefore going to point to the same place (typically .Pa /usr/ports.distfiles ) on every machine. .Bd -literal -offset 4n mkdir /usr/ports.distfiles mkdir /usr/ports.workdir .Ed .Sh BUILDING KERNELS Here is how you build a -STABLE kernel (on your main development box). If you want to create a custom kernel, copy .Pa GENERIC to .Pa KERNELNAME and then edit it before configuring and building. The kernel configuration file lives in .Pa /usr/src/sys/i386/conf/KERNELNAME . .Bd -literal -offset 4n cd /usr/src make buildkernel KERNCONF=KERNELNAME .Ed .Pp .Sy WARNING! If you are familiar with the old config/cd/make method of building a -STABLE kernel, note that the .Xr config 8 method will put the build environment in .Pa /usr/src/sys/i386/compile/KERNELNAME instead of in .Pa /usr/obj . .Pp Building a -CURRENT kernel .Bd -literal -offset 4n cd /usr/src2 (on the master server) make buildkernel KERNCONF=KERNELNAME .Ed .Sh INSTALLING KERNELS Installing a -STABLE kernel (typically done on a client, only do this on your main development server if you want to install a new kernel for your main development server): .Bd -literal -offset 4n cd /usr/src make installkernel KERNCONF=KERNELNAME .Ed .Pp If you are using the older config/cd/make build mechanism for -STABLE, you would install using: .Bd -literal -offset 4n cd /usr/src/sys/i386/compile/KERNELNAME make install .Ed .Pp Installing a -CURRENT kernel (typically done only on a client) .Bd -literal -offset 4n (remember /usr/src is pointing to the client's specific environment) cd /usr/src make installkernel KERNCONF=KERNELNAME .Ed .Sh BUILDING THE WORLD This environment is designed such that you do all builds on the master server, and then install from each client. You can do builds on a client only if .Pa /usr/obj is local to that client. Building the world is easy: .Bd -literal -offset 4n cd /usr/src make buildworld .Ed .Pp If you are on the master server you are running in a -STABLE environment, but that does not prevent you from building the -CURRENT world. Just .Xr cd 1 into the appropriate source directory and you are set. Do not accidentally install it on your master server though! .Bd -literal -offset 4n cd /usr/src2 make buildworld .Ed .Sh INSTALLING THE WORLD You can build on your main development server and install on clients. The main development server must export .Pa /FreeBSD and .Pa /usr/obj via read-only NFS to the clients. .Pp .Em NOTE!!! If .Pa /usr/obj is a softlink on the master server, it must also be the EXACT SAME softlink on each client. If .Pa /usr/obj is a directory in .Pa /usr or a mount point on the master server, then it must be (interchangeably) a directory in .Pa /usr or a mount point on each client. This is because the absolute paths are expected to be the same when building the world as when installing it, and you generally build it on your main development box and install it from a client. If you do not set up .Pa /usr/obj properly you will not be able to build on machine and install on another. .Bd -literal -offset 4n (ON THE CLIENT) (remember /usr/src is pointing to the client's specific environment) cd /usr/src make installworld .Ed .Pp .Sy WARNING! If builds work on the master server but installs do not work from the clients, for example you try to install and the client complains that the install tried to write into the read-only .Pa /usr/obj , then it is likely that the .Xr make.conf 5 file on the client does not match the one on the master server closely enough and the install is trying to install something that was not built. .Sh DOING DEVELOPMENT ON A CLIENT (NOT JUST INSTALLING) Developers often want to run buildkernel's or buildworld's on client boxes simply to life-test the box. You do this in the same manner that you buildkernel and buildworld on your master server. All you have to do is make sure that .Pa /usr/obj is pointing to local storage. If you followed my advise and made .Pa /usr/obj its own partition on the master server, then it is typically going to be an NFS mount on the client. Simply unmounting .Pa /usr/obj will leave you with a .Pa /usr/obj that is a subdirectory in .Pa /usr which is typically local to the client. You can then do builds to your heart's content! .Sh MAINTAINING A LOCAL BRANCH There is absolutely nothing preventing you from breaking out other versions of the source tree into .Pa /FreeBSD/XXX . In fact, my .Pa /FreeBSD partition also contains .Ox , .Nx , and various flavors of .Tn Linux . You may not necessarily be able to build .Pf non- Fx operating systems on your master server, but being able to collect and manage source distributions from a central server is a very useful thing to be able to do and you can certainly export to machines which can build those other operating systems. .Pp Many developers choose to maintain a local branch of .Fx to test patches or build a custom distribution. This can be done with svn or another source code management system (git, mercurial, Perforce, BitKeeper) with its own repository. .Sh "UPDATING VIA SVN" By using a .Xr cron 8 job to maintain an updated svn repository, the source tree can be updated at any time as follows: .Bd -literal -offset 4n (on the main development server) cd /usr svn update src doc ports .Ed .Pp It is that simple, and since you are exporting the whole lot to your clients, your clients have immediate visibility into the updated source. This is a good time to also remind you that most of the .Xr svn 1 operations you do will be done as .Dq Li root . .Sh SEE ALSO .Xr crontab 1 , .Xr crontab 5 , .Xr make.conf 5 , .Xr build 7 , .Xr firewall 7 , .Xr release 7 , .Xr tuning 7 , +.Xr tests 7 , .Xr diskless 8 .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 . Index: stable/11/share/man/man7/tests.7 =================================================================== --- stable/11/share/man/man7/tests.7 (revision 366235) +++ stable/11/share/man/man7/tests.7 (revision 366236) @@ -1,239 +1,240 @@ .\" $FreeBSD$ .\" $NetBSD: tests.kyua.7,v 1.2 2013/07/20 21:39:59 wiz Exp $ .\" .\" Copyright (c) 2010 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. .\" -.Dd August 21, 2017 +.Dd August 19, 2020 .Dt TESTS 7 .Os .Sh NAME .Nm tests .Nd introduction to the .Fx Test Suite .Sh DESCRIPTION The .Fx Test Suite provides a collection of automated tests for two major purposes. On one hand, the test suite aids .Em developers to detect bugs and regressions when they modify the source tree. On the other hand, it allows .Em end users (and, in particular, system administrators) to verify that fresh installations of the .Fx operating system behave correctly on their hardware platform and also to ensure that the system does not suffer from regressions during regular operation and maintenance. .Pp The .Fx Test Suite can be found in the .Pa /usr/tests hierarchy. .Pp This manual page describes how to run the test suite and how to configure some of its optional features. .Ss Installing the test suite The test suite is installed by default as of .Fx 11.0-RELEASE. .Pp If the .Pa /usr/tests directory is missing, then you will have to enable the build of the test suite, rebuild your system and install the results. You can do so by setting .Sq WITH_TESTS=yes in your .Pa /etc/src.conf file (see .Xr src.conf 5 for details) and rebuilding the system as described in .Xr build 7 . .Ss When to run the tests? Before diving into the details of how to run the test suite, here are some scenarios in which you should run it: .Bl -bullet -offset indent .It After a fresh installation of .Fx to ensure that the system works correctly on your hardware platform. .It After an upgrade of .Fx to a different version to ensure that the new code works well on your hardware platform and that the upgrade did not introduce regressions in your configuration. .It After modifying the source tree to detect any new bugs and/or regressions. .It Periodically, maybe from a .Xr cron 8 job, to ensure that any changes to the system (such as the installation of third-party packages or manual modifications to configuration files) do not introduce unexpected failures. .El .Ss Running the tests First, you will need to install the .Sq devel/kyua package from .Xr ports 7 . Then use the following command to run the whole test suite: .Bd -literal -offset indent $ kyua test -k /usr/tests/Kyuafile .Ed .Pp The above will iterate through all test programs in .Pa /usr/tests recursively, execute them, store their results and debugging data in Kyua's database (by default in .Pa ~/.kyua/store.db ) , and print a summary of the results. This summary includes a brief count of all total tests run and how many of them failed. .Pp It is possible to restrict which tests to run by providing their names in the command line. For example, this would execute the tests for the .Xr cp 1 and .Xr cut 1 utilities: .Bd -literal -offset indent $ kyua test -k /usr/tests/Kyuafile bin/cp usr.bin/cut .Ed .Ss Obtaining reports of the tests execution Additional information about the test results can be retrieved by using Kyua's various reporting commands. For example, the following would print a plain-text report of the executed tests and show which ones failed: .Bd -literal -offset indent $ kyua report .Ed .Pp This example would generate an HTML report ready to be published on a web server: .Bd -literal -offset indent $ kyua report-html --output ~/public_html/tests .Ed .Pp For further details on the command-line interface of Kyua, please refer to its manual page .Xr kyua 1 . .Ss Configuring the tests Some test cases in the .Fx Test Suite require manual configuration by the administrator before they can be run. Unless certain properties are defined, the tests that require them will be skipped. .Pp Test suites are configured by defining their configuration variables in .Pa /usr/local/etc/kyua/kyua.conf . The format of this file is detailed in .Xr kyua.conf 5 . .Pp The following configuration variables are available in the .Fx Test Suite: .Bl -tag -width "allow_sysctl_side_effects" .It allow_devfs_side_effects If defined, enables tests that may destroy and recreate semipermanent device nodes, like disk devices. Without this variable, tests may still create and destroy devices nodes that are normally transient, like /dev/tap* and /dev/pts*, as long as they clean them up afterwards. However, tests that require this variable have a relaxed cleanup requirement; they must recreate any devices that they destroyed, but not necessarily with the same devnames. .It allow_sysctl_side_effects Enables tests that change globally significant .Xr sysctl 8 variables. The tests will undo any changes in their cleanup phases. .It disks Must be set to a space delimited list of disk device nodes. Tests that need destructive access to disks must use these devices. Tests are not required to preserve any data present on these disks. .It fibs Must be set to a space delimited list of FIBs (routing tables). Tests that need to modify a routing table may use any of these. Tests will cleanup any new routes that they create. .El .Ss What to do if something fails? If there is .Em any failure during the execution of the test suite, please consider reporting it to the .Fx developers so that the failure can be analyzed and fixed. To do so, either send a message to the appropriate mailing list or file a problem report. For more details please refer to: .Bl -bullet -offset indent -compact .It .Lk http://lists.freebsd.org/ "FreeBSD Mailing Lists" .It .Lk http://www.freebsd.org/support.html "Problem Reporting" .El .Sh FILES .Bl -tag -compact -width usrXlocalXetcXkyuaXkyuaXconfXX .It Pa /usr/local/etc/kyua/kyua.conf System-wide configuration file for .Xr kyua 1 . .It Pa ~/.kyua/kyua.conf User-specific configuration file for .Xr kyua 1 ; overrides the system file. .It Pa ~/.kyua/store.db Default result database used by Kyua. .It Pa /usr/tests/ Location of the .Fx Test Suite. .It Pa /usr/tests/Kyuafile Top-level test suite definition file. .El .Sh SEE ALSO .Xr kyua 1 , -.Xr build 7 +.Xr build 7 , +.Xr development 7 .Sh HISTORY The .Fx Test Suite first appeared in .Fx 10.1 . .Pp The .Nm manual page first appeared in .Nx 6.0 and was later ported to .Fx 10.1 . .Sh AUTHORS .An Julio Merino Aq Mt jmmv@FreeBSD.org Index: stable/11 =================================================================== --- stable/11 (revision 366235) +++ stable/11 (revision 366236) Property changes on: stable/11 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head:r364387