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 information 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 or
70 subdirectory of those directories has the same effect as issuing the
71 same command in all subdirectories of that directory.
72 With no target specified, the things in that directory are just built.
74 A source tree is allowed to be read-only.
77 objects are usually built in a separate object directory hierarchy
78 specified by the environment variable
79 .Va MAKEOBJDIRPREFIX ,
85 The canonical object directory is described in the documentation for the
89 The build may be controlled by defining
91 variables described in the
93 section below, and by the variables documented in
96 The following list provides the names and actions for the targets
97 supported by the build system:
98 .Bl -tag -width ".Cm cleandepend"
100 Run Clang static analyzer against all objects and present output on stdout.
102 Run tests for a given subdirectory.
103 The default directory used is
105 but the check directory can be changed with
110 test suite on installed world.
112 Remove any files created during the build process.
115 .Pa ${.OBJDIR}/${DEPENDFILE}*
116 files generated by prior
122 Remove the canonical object directory if it exists, or perform
123 actions equivalent to
124 .Dq Li "make clean cleandepend"
126 This target will also remove an
132 It is advisable to run
133 .Dq Li "make cleandir"
134 twice: the first invocation will remove the canonical object directory
135 and the second one will clean up
138 Generate a list of build dependencies in file
139 .Pa ${.OBJDIR}/${DEPENDFILE} .
140 Per-object dependencies are generated at build time and stored in
141 .Pa ${.OBJDIR}/${DEPENDFILE}.${OBJ} .
143 Install the results of the build to the appropriate location in the
144 installation directory hierarchy specified in variable
147 Create the canonical object directory associated with the current
150 Create a symbolic link to the canonical object directory in
153 Generate a tags file using the program specified in the
157 The build system supports
163 The other supported targets under directory
166 .Bl -tag -width ".Cm distributeworld"
168 Spawn an interactive shell with environment variables set up for
169 building the system or individual components.
170 For cross-building the target architecture needs to be specified with
177 This target is only useful after a complete toolchain (including
178 the compiler, linker, assembler, headers and libraries) has been
183 Build everything but the kernel, configure files in
187 The object directory can be changed from the default
193 The actual build location prefix used
195 .Va WITH_UNIFIED_OBJDIR
199 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH}
202 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
203 for native builds, and
204 .Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}${.CURDIR}
205 for cross builds and native builds with variable
206 .Va CROSS_BUILD_TESTING
209 Attempt to clean up targets built by a preceding
211 or similar step built from this source directory.
214 .Va WITH_UNIFIED_OBJDIR
215 is enabled, attempt to clean up targets built by a preceding
218 or similar step, for any architecture built from this source directory.
219 .It Cm distributeworld
220 Distribute everything compiled by a preceding
223 Files are placed in the directory hierarchy specified by
227 This target is used while building a release; see
230 This target builds a cross-toolchain for the given
234 as well as a select list of static userland tools for the host system.
235 This is intended to be used in a jail where QEMU is used to improve
236 performance by avoiding emulating binaries that do not need to be emulated.
241 .It Cm native-xtools-install
242 Installs the results to
243 .Pa ${DESTDIR}/${NXTP}
253 Archive the results of
254 .Cm distributeworld ,
255 placing the results in
257 This target is used while building a release; see
260 Install everything built by a preceding
262 step into the directory hierarchy pointed to by
267 If installing onto an NFS file system and running
271 option, make sure that
273 is running on both client and server.
276 on how to make it start at boot time.
278 Create the build toolchain needed to build the rest of the system.
279 For cross-architecture builds, this step creates a cross-toolchain.
281 For each architecture,
286 for all kernels for that architecture,
289 This command takes a long time.
295 defined so only the kernels for each architecture are built.
301 defined so only the worlds for each architecture are built.
303 Get updated sources as configured in
306 Print a list of supported
310 pairs for world and kernel targets.
312 Execute the same targets as
314 In addition print a summary of all failed targets at the end and
315 exit with an error if there were any.
317 Create a build toolchain for each architecture supported by the build system.
319 Builds and installs a cross-toolchain and sysroot for the given
323 The sysroot contains target library and headers.
324 The target is an alias for
328 The location of the files installed can be controlled with
330 The target location in
333 .Pa ${DESTDIR}/${XDTP}
341 .Pa ${TARGET_ARCH}-freebsd .
347 Installs the files for the
351 Installs autoconf-style symlinks to
352 .Pa ${DESTDIR}/usr/bin
353 pointing into the xdev toolchain in
354 .Pa ${DESTDIR}/${XDTP} .
357 Kernel specific build targets in
360 .Bl -tag -width ".Cm distributekernel"
362 Rebuild the kernel and the kernel modules.
363 The object directory can be changed from the default
370 Install the kernel and the kernel modules to directory
371 .Pa ${DESTDIR}/boot/kernel ,
372 renaming any pre-existing directory with this name to
374 if it contained the currently running kernel.
375 The target directory under
377 may be modified using the
383 .It Cm distributekernel
384 Install the kernel to the directory
385 .Pa ${DISTDIR}/kernel/boot/kernel .
386 This target is used while building a release; see
389 Archive the results of
390 .Cm distributekernel ,
391 placing the results in
393 This target is used while building a release; see
400 .It Cm kernel-toolchain
401 Rebuild the tools needed for kernel compilation.
402 Use this if you did not do a
405 .It Cm reinstallkernel
406 Reinstall the kernel and the kernel modules, overwriting the contents
407 of the target directory.
410 target, the target directory can be specified using the
416 Convenience targets for cleaning up the install destination directory
420 .Bl -tag -width ".Cm delete-old-libs"
422 Print a list of old files and directories in the system.
424 Delete obsolete base system files and directories interactively.
426 .Li -DBATCH_DELETE_OLD_FILES
427 is specified at the command line, the delete operation will be
434 should be set as with
435 .Dq Li "make installworld" .
436 .It Cm delete-old-libs
437 Delete obsolete base system libraries interactively.
438 This target should only be used if no third party software uses these
441 .Li -DBATCH_DELETE_OLD_FILES
442 is specified at the command line, the delete operation will be
449 should be set as with
450 .Dq Li "make installworld" .
453 Variables that influence all builds include:
454 .Bl -tag -width ".Va MAKEOBJDIRPREFIX"
456 Defines a set of debugging flags that will be used to build all userland
465 targets install binaries from the current
468 so that debugging information is retained in the installed binaries.
470 The directory hierarchy prefix where built objects will be installed.
473 defaults to the empty string.
474 .It Va MAKEOBJDIRPREFIX
475 Defines the prefix for directory names in the tree of built objects.
479 This variable should only be set in the environment or
480 .Pa /etc/src-env.conf
487 If defined, compiler warnings will not cause the build to halt,
488 even if the makefile says otherwise.
490 If defined, the build process will run the DTrace CTF conversion
491 tools on built objects.
494 Additionally, builds in
496 are influenced by the following
499 .Bl -tag -width ".Va SUBDIR_OVERRIDE"
501 Overrides which kernel to build and install for the various kernel
506 Overrides the directory in which
508 and any files included by
512 .Pa sys/${ARCH}/conf .
514 If set, the build target
518 .Va NO_KERNELCONFIG ,
521 When set to a value other than
525 is set to the value of
528 If set, this variable supplies a list of additional directories relative to
529 the root of the source tree to build as part of the
532 The directories are built in parallel with each other,
533 and with the base system directories.
536 directive at the beginning of the
538 list to ensure all base system directories are built first.
540 may also be used as needed elsewhere within the list.
542 If set, this variable supplies a list of additional tools that are used by the
547 .It Va LOCAL_LIB_DIRS
548 If set, this variable supplies a list of additional directories relative to
549 the root of the source tree to build as part of the
552 The directories are built in parallel with each other,
553 and with the base system libraries.
556 directive at the beginning of the
558 list to ensure all base system libraries are built first.
560 may also be used as needed elsewhere within the list.
562 If set, this variable supplies a list of additional mtrees relative to the
563 root of the source tree to use as part of the
566 .It Va LOCAL_TOOL_DIRS
567 If set, this variable supplies a list of additional directories relative to
568 the root of the source tree to build as part of the
571 .It Va LOCAL_XTOOL_DIRS
572 If set, this variable supplies a list of additional directories relative to
573 the root of the source tree to build as part of the
577 A list of ports with kernel modules that should be built and installed
583 .Bd -literal -offset indent
584 make PORTS_MODULES=emulators/kqemu-kmod kernel
587 Command to use at install time when stripping binaries.
588 Be sure to add any additional tools required to run
593 variable before running the
601 .It Va SUBDIR_OVERRIDE
602 Override the default list of sub-directories and only build the
603 sub-directory named in this variable.
606 then all libraries and includes, and some of the build tools will still build
612 will only build the specified directory as was done historically.
615 it is necesarry to override
617 with any custom directories containing libraries.
618 This allows building a subset of the system in the same way as
620 does using its sysroot handling.
621 This variable can also be useful when debugging failed builds.
622 .Bd -literal -offset indent
623 make some-target SUBDIR_OVERRIDE=foo/bar
626 The target hardware platform.
627 This is analogous to the
630 This is necessary to cross-build some target architectures.
631 For example, cross-building for ARM64 machines requires
632 .Va TARGET_ARCH Ns = Ns Li aarch64
634 .Va TARGET Ns = Ns Li arm64 .
637 defaults to the current hardware platform, unless
639 is also set, in which case it defaults to the appropriate
640 value for that architecture.
642 The target machine processor architecture.
643 This is analogous to the
646 Set this to cross-build for a different architecture.
649 defaults to the current machine architecture, unless
651 is also set, in which case it defaults to the appropriate
652 value for that platform.
653 Typically, one only needs to set
657 Builds under directory
659 are also influenced by defining one or more of the following symbols,
664 .Bl -tag -width ".Va -DNO_KERNELCONFIG"
665 .It Va LOADER_DEFAULT_INTERP
666 Defines what interpreter the default loader program will have.
672 This creates the default link for
674 to the loader with that interpreter.
675 It also determines what interpreter is compiled into
678 If set, the build targets that clean parts of the object tree use the
684 If set, no object tree files are cleaned at all.
685 This is the default when
699 is set no kernel objects are cleaned either.
701 If set, the build process does not run the DTrace CTF conversion tools
704 If set, the build does not descend into the
706 subdirectory (i.e., manual pages, locale data files, timezone data files and
709 files will not be rebuild from their sources).
710 .It Va NO_KERNELCLEAN
711 If set, the build process does not run
716 .It Va NO_KERNELCONFIG
717 If set, the build process does not run
723 If set, the build process does not run
729 If set, the update process does not update the source of the
731 documentation as part of the
735 If set, the libraries phase will be skipped.
737 If set, no object directories will be created.
738 This should only be used if object directories were created in a
739 previous build and no new directories are connected.
740 .It Va NO_PORTSUPDATE
741 If set, the update process does not update the Ports tree as part of the
745 If set, the update process does not update the www tree as part of the
749 If set, the build target
754 and will skip most bootstrap phases.
755 It will only bootstrap libraries and build all of userland.
756 This option should be used only when it is known that none of the bootstrap
757 needs changed and that no new directories have been connected to the build.
760 Builds under directory
762 are influenced by the following
765 .Bl -tag -width ".Va DOC_LANG"
767 If set, restricts the documentation build to the language subdirectories
768 specified as its content.
769 The default action is to build documentation for all languages.
774 and related targets are influenced by the following
777 .Bl -tag -width ".Va MAKE_JUST_KERNELS"
779 Pass the value of this variable to each
781 invocation used to build worlds and kernels.
782 This can be used to enable multiple jobs within a single architecture's build
783 while still building each architecture serially.
784 .It Va MAKE_JUST_KERNELS
785 Only build kernels for each supported architecture.
786 .It Va MAKE_JUST_WORLDS
787 Only build worlds for each supported architecture.
788 .It Va WITHOUT_WORLDS
789 Only build kernels for each supported architecture.
790 .It Va WITHOUT_KERNELS
791 Only build worlds for each supported architecture.
792 .It Va UNIVERSE_TARGET
793 Execute the specified
795 target for each supported architecture instead of the default action of
796 building a world and one or more kernels.
797 This variable implies
798 .Va WITHOUT_KERNELS .
800 Only build the listed targets instead of each supported architecture.
802 In addition to the supported architectures, build the semi-supported
804 A semi-supported architecture has build support in the
806 tree, but receives significantly less testing and is generally for
807 fringe uses that do not have a wide appeal.
810 .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
811 .It Pa /usr/doc/Makefile
812 .It Pa /usr/doc/share/mk/doc.project.mk
813 .It Pa /usr/ports/Mk/bsd.port.mk
814 .It Pa /usr/ports/Mk/bsd.sites.mk
815 .It Pa /usr/share/examples/etc/make.conf
816 .It Pa /usr/src/Makefile
817 .It Pa /usr/src/Makefile.inc1
822 method of updating your system from the latest sources, please see the
827 The following sequence of commands can be used to cross-build the
828 system for the armv6 architecture on an amd64 host:
829 .Bd -literal -offset indent
831 make TARGET_ARCH=armv6 buildworld buildkernel
832 make TARGET_ARCH=armv6 DESTDIR=/clients/arm installworld installkernel
837 manpage first appeared in
856 .An Mike W. Meyer Aq Mt mwm@mired.org
projects / FreeBSD / FreeBSD.git / blob