4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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
32 .Nd General instructions on how to build the system
36 system and its applications are contained in three different directories,
42 These directories may be initially empty or non-existent until updated with
50 sources, which is loosely defined as the things required to rebuild
51 the system to a useful state.
54 contains the source for the system documentation, excluding the manual
58 contains a tree that provides a consistent interface for building and
59 installing third party applications.
60 For more information about the ports build process, see
65 command is used in each of these directories to build and install the
66 things in that directory.
69 command in any directory issues the
71 command recursively in all subdirectories.
72 With no target specified, the items in the directories are built
73 and no further action is taken.
75 A source tree is allowed to be read-only.
78 objects are usually built in a separate object directory hierarchy
79 specified by the environment variable
80 .Va MAKEOBJDIRPREFIX ,
86 The canonical object directory is described in the documentation for the
90 The build may be controlled by defining
92 variables described in the
94 section below, and by the variables documented in
97 The default components included in the build are specified in the file
100 To override the default file, include the SRCCONF option in the make steps,
101 pointing to a custom src.conf file.
102 For more information see
105 The following list provides the names and actions for the targets
106 supported by the build system:
107 .Bl -tag -width ".Cm cleandepend"
109 Run Clang static analyzer against all objects and present output on stdout.
111 Run tests for a given subdirectory.
112 The default directory used is
114 but the check directory can be changed with
119 test suite on installed world.
121 Remove any files created during the build process.
124 .Pa ${.OBJDIR}/${DEPENDFILE}*
125 files generated by prior
131 Remove the canonical object directory if it exists, or perform
132 actions equivalent to
133 .Dq Li "make clean cleandepend"
135 This target will also remove an
141 It is advisable to run
142 .Dq Li "make cleandir"
143 twice: the first invocation will remove the canonical object directory
144 and the second one will clean up
147 Generate a list of build dependencies in file
148 .Pa ${.OBJDIR}/${DEPENDFILE} .
149 Per-object dependencies are generated at build time and stored in
150 .Pa ${.OBJDIR}/${DEPENDFILE}.${OBJ} .
152 Install the results of the build to the appropriate location in the
153 installation directory hierarchy specified in variable
156 Create the canonical object directory associated with the current
159 Create a symbolic link to the canonical object directory in
162 Generate a tags file using the program specified in the
166 The build system supports
172 The other supported targets under directory
175 .Bl -tag -width ".Cm distributeworld"
177 Spawn an interactive shell with environment variables set up for
178 building the system or individual components.
179 For cross-building the target architecture needs to be specified with
186 This target is only useful after a complete toolchain (including
187 the compiler, linker, assembler, headers and libraries) has been
192 Build everything but the kernel, configure files in
196 The object directory can be changed from the default
202 The actual build location prefix used
204 .Va WITH_UNIFIED_OBJDIR
208 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH}
211 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
212 for native builds, and
213 .Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}${.CURDIR}
214 for cross builds and native builds with variable
215 .Va CROSS_BUILD_TESTING
218 Attempt to clean up targets built by a preceding
220 or similar step built from this source directory.
223 .Va WITH_UNIFIED_OBJDIR
224 is enabled, attempt to clean up targets built by a preceding
227 or similar step, for any architecture built from this source directory.
228 .It Cm distributeworld
229 Distribute everything compiled by a preceding
232 Files are placed in the directory hierarchy specified by
236 This target is used while building a release; see
239 This target builds a cross-toolchain for the given
243 as well as a select list of static userland tools for the host system.
244 This is intended to be used in a jail where QEMU is used to improve
245 performance by avoiding emulating binaries that do not need to be emulated.
250 .It Cm native-xtools-install
251 Installs the results to
252 .Pa ${DESTDIR}/${NXTP}
262 Archive the results of
263 .Cm distributeworld ,
264 placing the results in
266 This target is used while building a release; see
269 Install everything built by a preceding
271 step into the directory hierarchy pointed to by
276 If installing onto an NFS file system and running
280 option, make sure that
282 is running on both client and server.
285 on how to make it start at boot time.
287 Create the build toolchain needed to build the rest of the system.
288 For cross-architecture builds, this step creates a cross-toolchain.
290 For each architecture,
295 for all kernels for that architecture,
298 This command takes a long time.
304 defined so only the kernels for each architecture are built.
310 defined so only the worlds for each architecture are built.
312 Get updated sources as configured in
315 Print a list of supported
319 pairs for world and kernel targets.
321 Execute the same targets as
323 In addition print a summary of all failed targets at the end and
324 exit with an error if there were any.
326 Create a build toolchain for each architecture supported by the build system.
328 Builds and installs a cross-toolchain and sysroot for the given
332 The sysroot contains target library and headers.
333 The target is an alias for
337 The location of the files installed can be controlled with
339 The target location in
342 .Pa ${DESTDIR}/${XDTP}
350 .Pa ${TARGET_ARCH}-freebsd .
356 Installs the files for the
360 Installs autoconf-style symlinks to
361 .Pa ${DESTDIR}/usr/bin
362 pointing into the xdev toolchain in
363 .Pa ${DESTDIR}/${XDTP} .
366 Kernel specific build targets in
369 .Bl -tag -width ".Cm distributekernel"
371 Rebuild the kernel and the kernel modules.
372 The object directory can be changed from the default
379 Install the kernel and the kernel modules to directory
380 .Pa ${DESTDIR}/boot/kernel ,
381 renaming any pre-existing directory with this name to
383 if it contained the currently running kernel.
384 The target directory under
386 may be modified using the
392 .It Cm distributekernel
393 Install the kernel to the directory
394 .Pa ${DISTDIR}/kernel/boot/kernel .
395 This target is used while building a release; see
398 Archive the results of
399 .Cm distributekernel ,
400 placing the results in
402 This target is used while building a release; see
409 .It Cm kernel-toolchain
410 Rebuild the tools needed for kernel compilation.
411 Use this if you did not do a
414 .It Cm reinstallkernel
415 Reinstall the kernel and the kernel modules, overwriting the contents
416 of the target directory.
419 target, the target directory can be specified using the
425 Convenience targets for cleaning up the install destination directory
429 .Bl -tag -width ".Cm delete-old-libs"
431 Print a list of old files and directories in the system.
433 Delete obsolete base system files and directories interactively.
435 .Li -DBATCH_DELETE_OLD_FILES
436 is specified at the command line, the delete operation will be
443 should be set as with
444 .Dq Li "make installworld" .
445 .It Cm delete-old-libs
446 Delete obsolete base system libraries interactively.
447 This target should only be used if no third party software uses these
450 .Li -DBATCH_DELETE_OLD_FILES
451 is specified at the command line, the delete operation will be
458 should be set as with
459 .Dq Li "make installworld" .
462 Variables that influence all builds include:
463 .Bl -tag -width ".Va MAKEOBJDIRPREFIX"
465 Defines a set of debugging flags that will be used to build all userland
474 targets install binaries from the current
477 so that debugging information is retained in the installed binaries.
479 The directory hierarchy prefix where built objects will be installed.
482 defaults to the empty string.
483 .It Va MAKEOBJDIRPREFIX
484 Defines the prefix for directory names in the tree of built objects.
488 This variable should only be set in the environment or
489 .Pa /etc/src-env.conf
495 .It Va WITHOUT_WERROR
496 If defined, compiler warnings will not cause the build to halt,
497 even if the makefile says otherwise.
499 If defined, the build process will run the DTrace CTF conversion
500 tools on built objects.
503 Additionally, builds in
505 are influenced by the following
508 .Bl -tag -width ".Va SUBDIR_OVERRIDE"
510 Overrides which kernel to build and install for the various kernel
515 Overrides the directory in which
517 and any files included by
521 .Pa sys/${ARCH}/conf .
523 If set, the build target
527 .Va NO_KERNELCONFIG ,
530 When set to a value other than
534 is set to the value of
537 If set, this variable supplies a list of additional directories relative to
538 the root of the source tree to build as part of the
541 The directories are built in parallel with each other,
542 and with the base system directories.
545 directive at the beginning of the
547 list to ensure all base system directories are built first.
549 may also be used as needed elsewhere within the list.
551 If set, this variable supplies a list of additional tools that are used by the
556 .It Va LOCAL_LIB_DIRS
557 If set, this variable supplies a list of additional directories relative to
558 the root of the source tree to build as part of the
561 The directories are built in parallel with each other,
562 and with the base system libraries.
565 directive at the beginning of the
567 list to ensure all base system libraries are built first.
569 may also be used as needed elsewhere within the list.
571 If set, this variable supplies a list of additional mtrees relative to the
572 root of the source tree to use as part of the
575 .It Va LOCAL_LEGACY_DIRS
576 If set, this variable supplies a list of additional directories relative to
577 the root of the source tree to build as part of the
580 .It Va LOCAL_BSTOOL_DIRS
581 If set, this variable supplies a list of additional directories relative to
582 the root of the source tree to build as part of the
585 .It Va LOCAL_TOOL_DIRS
586 If set, this variable supplies a list of additional directories relative to
587 the root of the source tree to build as part of the
590 .It Va LOCAL_XTOOL_DIRS
591 If set, this variable supplies a list of additional directories relative to
592 the root of the source tree to build as part of the
596 A list of ports with kernel modules that should be built and installed
602 .Bd -literal -offset indent
603 make PORTS_MODULES=emulators/virtualbox-ose-kmod kernel
606 A list of external kernel modules that should be built and installed
612 .It Va LOCAL_MODULES_DIR
613 The directory in which to search for the kernel modules specified by
615 Each kernel module should consist of a directory containing a makefile.
617 .Pa ${LOCALBASE}/sys/modules .
619 Specify a file to override the default
621 The src.conf file controls the components to build.
625 Command to use at install time when stripping binaries.
626 Be sure to add any additional tools required to run
631 variable before running the
639 .It Va SUBDIR_OVERRIDE
640 Override the default list of sub-directories and only build the
641 sub-directory named in this variable.
644 then all libraries and includes, and some of the build tools will still build
650 will only build the specified directory as was done historically.
653 it is necesarry to override
655 with any custom directories containing libraries.
656 This allows building a subset of the system in the same way as
658 does using its sysroot handling.
659 This variable can also be useful when debugging failed builds.
660 .Bd -literal -offset indent
661 make some-target SUBDIR_OVERRIDE=foo/bar
664 The target hardware platform.
665 This is analogous to the
668 This is necessary to cross-build some target architectures.
669 For example, cross-building for ARM64 machines requires
670 .Va TARGET_ARCH Ns = Ns Li aarch64
672 .Va TARGET Ns = Ns Li arm64 .
675 defaults to the current hardware platform, unless
677 is also set, in which case it defaults to the appropriate
678 value for that architecture.
680 The target machine processor architecture.
681 This is analogous to the
684 Set this to cross-build for a different architecture.
687 defaults to the current machine architecture, unless
689 is also set, in which case it defaults to the appropriate
690 value for that platform.
691 Typically, one only needs to set
695 Builds under directory
697 are also influenced by defining one or more of the following symbols,
702 .Bl -tag -width ".Va -DNO_KERNELCONFIG"
703 .It Va LOADER_DEFAULT_INTERP
704 Defines what interpreter the default loader program will have.
710 This creates the default link for
712 to the loader with that interpreter.
713 It also determines what interpreter is compiled into
716 If set, the build targets that clean parts of the object tree use the
722 If set, no object tree files are cleaned at all.
723 This is the default when
737 is set no kernel objects are cleaned either.
739 If set, the build process does not run the DTrace CTF conversion tools
742 If set, the build does not descend into the
744 subdirectory (i.e., manual pages, locale data files, timezone data files and
747 files will not be rebuild from their sources).
748 .It Va NO_KERNELCLEAN
749 If set, the build process does not run
754 .It Va NO_KERNELCONFIG
755 If set, the build process does not run
761 If set, the build process does not run
767 If set, the update process does not update the source of the
769 documentation as part of the
773 If set, the libraries phase will be skipped.
775 If set, no object directories will be created.
776 This should only be used if object directories were created in a
777 previous build and no new directories are connected.
778 .It Va NO_PORTSUPDATE
779 If set, the update process does not update the Ports tree as part of the
783 If set, the update process does not update the www tree as part of the
787 If set, the build target
792 and will skip most bootstrap phases.
793 It will only bootstrap libraries and build all of userland.
794 This option should be used only when it is known that none of the bootstrap
795 needs changed and that no new directories have been connected to the build.
798 Builds under directory
800 are influenced by the following
803 .Bl -tag -width ".Va DOC_LANG"
805 If set, restricts the documentation build to the language subdirectories
806 specified as its content.
807 The default action is to build documentation for all languages.
812 and related targets are influenced by the following
815 .Bl -tag -width ".Va MAKE_JUST_KERNELS"
817 Pass the value of this variable to each
819 invocation used to build worlds and kernels.
820 This can be used to enable multiple jobs within a single architecture's build
821 while still building each architecture serially.
822 .It Va MAKE_JUST_KERNELS
823 Only build kernels for each supported architecture.
824 .It Va MAKE_JUST_WORLDS
825 Only build worlds for each supported architecture.
826 .It Va WITHOUT_WORLDS
827 Only build kernels for each supported architecture.
828 .It Va WITHOUT_KERNELS
829 Only build worlds for each supported architecture.
830 .It Va UNIVERSE_TARGET
831 Execute the specified
833 target for each supported architecture instead of the default action of
834 building a world and one or more kernels.
835 This variable implies
836 .Va WITHOUT_KERNELS .
838 Only build the listed targets instead of each supported architecture.
840 In addition to the supported architectures, build the semi-supported
842 A semi-supported architecture has build support in the
844 tree, but receives significantly less testing and is generally for
845 fringe uses that do not have a wide appeal.
848 .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
849 .It Pa /usr/doc/Makefile
850 .It Pa /usr/doc/share/mk/doc.project.mk
851 .It Pa /usr/ports/Mk/bsd.port.mk
852 .It Pa /usr/ports/Mk/bsd.sites.mk
853 .It Pa /usr/share/examples/etc/make.conf
854 .It Pa /usr/src/Makefile
855 .It Pa /usr/src/Makefile.inc1
860 method of updating your system from the latest sources, please see the
865 The following sequence of commands can be used to cross-build the
866 system for the armv6 architecture on an amd64 host:
867 .Bd -literal -offset indent
869 make TARGET_ARCH=armv6 buildworld buildkernel
870 make TARGET_ARCH=armv6 DESTDIR=/clients/arm installworld installkernel
875 manpage first appeared in
895 .An Mike W. Meyer Aq Mt mwm@mired.org
projects / FreeBSD / FreeBSD.git / blob