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
52 sources, which is loosely defined as the things required to rebuild
53 the system to a useful state.
56 contains the source for the system documentation, excluding the manual
60 contains a tree that provides a consistent interface for building and
61 installing third party applications.
62 For more information about the ports build process, see
67 command is used in each of these directories to build and install the
68 things in that directory.
71 command in any directory or
72 subdirectory of those directories has the same effect as issuing the
73 same command in all subdirectories of that directory.
74 With no target specified, the things in that directory are just built.
76 A source tree is allowed to be read-only.
79 objects are usually built in a separate object directory hierarchy
80 specified by the environment variable
81 .Va MAKEOBJDIRPREFIX ,
87 The canonical object directory is described in the documentation for the
91 The build may be controlled by defining
93 variables described in the
95 section below, and by the variables documented in
98 The following list provides the names and actions for the targets
99 supported by the build system:
100 .Bl -tag -width ".Cm cleandepend"
102 Run Clang static analyzer against all objects and present output on stdout.
104 Run tests for a given subdirectory.
105 The default directory used is
107 but the check directory can be changed with
112 test suite on installed world.
114 Remove any files created during the build process.
117 .Pa ${.OBJDIR}/${DEPENDFILE}*
118 files generated by prior
124 Remove the canonical object directory if it exists, or perform
125 actions equivalent to
126 .Dq Li "make clean cleandepend"
128 This target will also remove an
134 It is advisable to run
135 .Dq Li "make cleandir"
136 twice: the first invocation will remove the canonical object directory
137 and the second one will clean up
140 Generate a list of build dependencies in file
141 .Pa ${.OBJDIR}/${DEPENDFILE} .
142 Per-object dependencies are generated at build time and stored in
143 .Pa ${.OBJDIR}/${DEPENDFILE}.${OBJ} .
145 Install the results of the build to the appropriate location in the
146 installation directory hierarchy specified in variable
149 Create the canonical object directory associated with the current
152 Create a symbolic link to the canonical object directory in
155 Generate a tags file using the program specified in the
159 The build system supports
165 The other supported targets under directory
168 .Bl -tag -width ".Cm distributeworld"
170 Spawn an interactive shell with environment variables set up for
171 building the system or individual components.
172 For cross-building the target architecture needs to be specified with
179 This target is only useful after a complete toolchain (including
180 the compiler, linker, assembler, headers and libraries) has been
185 Build everything but the kernel, configure files in
189 The object directory can be changed from the default
195 The actual build location prefix used
197 .Va WITH_UNIFIED_OBJDIR
201 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH}
204 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
205 for native builds, and
206 .Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}${.CURDIR}
207 for cross builds and native builds with variable
208 .Va CROSS_BUILD_TESTING
211 Attempt to clean up targets built by a preceding
213 or similar step built from this source directory.
216 .Va WITH_UNIFIED_OBJDIR
217 is enabled, attempt to clean up targets built by a preceding
220 or similar step, for any architecture built from this source directory.
221 .It Cm distributeworld
222 Distribute everything compiled by a preceding
225 Files are placed in the directory hierarchy specified by
229 This target is used while building a release; see
232 This target builds a cross-toolchain for the given
236 as well as a select list of static userland tools for the host system.
237 This is intended to be used in a jail where QEMU is used to improve
238 performance by avoiding emulating binaries that do not need to be emulated.
243 .It Cm native-xtools-install
244 Installs the results to
245 .Pa ${DESTDIR}/${NXTP}
255 Archive the results of
256 .Cm distributeworld ,
257 placing the results in
259 This target is used while building a release; see
262 Install everything built by a preceding
264 step into the directory hierarchy pointed to by
269 If installing onto an NFS file system and running
273 option, make sure that
275 is running on both client and server.
278 on how to make it start at boot time.
280 Create the build toolchain needed to build the rest of the system.
281 For cross-architecture builds, this step creates a cross-toolchain.
283 For each architecture,
288 for all kernels for that architecture,
291 This command takes a long time.
297 defined so only the kernels for each architecture are built.
303 defined so only the worlds for each architecture are built.
305 Get updated sources as configured in
308 Print a list of supported
312 pairs for world and kernel targets.
314 Execute the same targets as
316 In addition print a summary of all failed targets at the end and
317 exit with an error if there were any.
319 Create a build toolchain for each architecture supported by the build system.
321 Builds and installs a cross-toolchain and sysroot for the given
325 The sysroot contains target library and headers.
326 The target is an alias for
330 The location of the files installed can be controlled with
332 The target location in
335 .Pa ${DESTDIR}/${XDTP}
343 .Pa ${TARGET_ARCH}-freebsd .
349 Installs the files for the
353 Installs autoconf-style symlinks to
354 .Pa ${DESTDIR}/usr/bin
355 pointing into the xdev toolchain in
356 .Pa ${DESTDIR}/${XDTP} .
359 Kernel specific build targets in
362 .Bl -tag -width ".Cm distributekernel"
364 Rebuild the kernel and the kernel modules.
365 The object directory can be changed from the default
372 Install the kernel and the kernel modules to directory
373 .Pa ${DESTDIR}/boot/kernel ,
374 renaming any pre-existing directory with this name to
376 if it contained the currently running kernel.
377 The target directory under
379 may be modified using the
385 .It Cm distributekernel
386 Install the kernel to the directory
387 .Pa ${DISTDIR}/kernel/boot/kernel .
388 This target is used while building a release; see
391 Archive the results of
392 .Cm distributekernel ,
393 placing the results in
395 This target is used while building a release; see
402 .It Cm kernel-toolchain
403 Rebuild the tools needed for kernel compilation.
404 Use this if you did not do a
407 .It Cm reinstallkernel
408 Reinstall the kernel and the kernel modules, overwriting the contents
409 of the target directory.
412 target, the target directory can be specified using the
418 Convenience targets for cleaning up the install destination directory
422 .Bl -tag -width ".Cm delete-old-libs"
424 Print a list of old files and directories in the system.
426 Delete obsolete base system files and directories interactively.
428 .Li -DBATCH_DELETE_OLD_FILES
429 is specified at the command line, the delete operation will be
436 should be set as with
437 .Dq Li "make installworld" .
438 .It Cm delete-old-libs
439 Delete obsolete base system libraries interactively.
440 This target should only be used if no third party software uses these
443 .Li -DBATCH_DELETE_OLD_FILES
444 is specified at the command line, the delete operation will be
451 should be set as with
452 .Dq Li "make installworld" .
455 Variables that influence all builds include:
456 .Bl -tag -width ".Va MAKEOBJDIRPREFIX"
458 Defines a set of debugging flags that will be used to build all userland
467 targets install binaries from the current
470 so that debugging information is retained in the installed binaries.
472 The directory hierarchy prefix where built objects will be installed.
475 defaults to the empty string.
476 .It Va MAKEOBJDIRPREFIX
477 Defines the prefix for directory names in the tree of built objects.
481 This variable should only be set in the environment or
482 .Pa /etc/src-env.conf
489 If defined, compiler warnings will not cause the build to halt,
490 even if the makefile says otherwise.
492 If defined, the build process will run the DTrace CTF conversion
493 tools on built objects.
496 Additionally, builds in
498 are influenced by the following
501 .Bl -tag -width ".Va SUBDIR_OVERRIDE"
503 Overrides which kernel to build and install for the various kernel
508 Overrides the directory in which
510 and any files included by
514 .Pa sys/${ARCH}/conf .
516 If set, the build target
520 .Va NO_KERNELCONFIG ,
523 When set to a value other than
527 is set to the value of
530 If set, this variable supplies a list of additional directories relative to
531 the root of the source tree to build as part of the
534 The directories are built in parallel with each other,
535 and with the base system directories.
538 directive at the beginning of the
540 list to ensure all base system directories are built first.
542 may also be used as needed elsewhere within the list.
544 If set, this variable supplies a list of additional tools that are used by the
549 .It Va LOCAL_LIB_DIRS
550 If set, this variable supplies a list of additional directories relative to
551 the root of the source tree to build as part of the
554 The directories are built in parallel with each other,
555 and with the base system libraries.
558 directive at the beginning of the
560 list to ensure all base system libraries are built first.
562 may also be used as needed elsewhere within the list.
564 If set, this variable supplies a list of additional mtrees relative to the
565 root of the source tree to use as part of the
568 .It Va LOCAL_TOOL_DIRS
569 If set, this variable supplies a list of additional directories relative to
570 the root of the source tree to build as part of the
573 .It Va LOCAL_XTOOL_DIRS
574 If set, this variable supplies a list of additional directories relative to
575 the root of the source tree to build as part of the
579 A list of ports with kernel modules that should be built and installed
585 .Bd -literal -offset indent
586 make PORTS_MODULES=emulators/kqemu-kmod kernel
589 Command to use at install time when stripping binaries.
590 Be sure to add any additional tools required to run
595 variable before running the
603 .It Va SUBDIR_OVERRIDE
604 Override the default list of sub-directories and only build the
605 sub-directory named in this variable.
608 then all libraries and includes, and some of the build tools will still build
614 will only build the specified directory as was done historically.
617 it is necesarry to override
619 with any custom directories containing libraries.
620 This allows building a subset of the system in the same way as
622 does using its sysroot handling.
623 This variable can also be useful when debugging failed builds.
624 .Bd -literal -offset indent
625 make some-target SUBDIR_OVERRIDE=foo/bar
628 The target hardware platform.
629 This is analogous to the
632 This is necessary to cross-build some target architectures.
633 For example, cross-building for ARM64 machines requires
634 .Va TARGET_ARCH Ns = Ns Li aarch64
636 .Va TARGET Ns = Ns Li arm64 .
639 defaults to the current hardware platform, unless
641 is also set, in which case it defaults to the appropriate
642 value for that architecture.
644 The target machine processor architecture.
645 This is analogous to the
648 Set this to cross-build for a different architecture.
651 defaults to the current machine architecture, unless
653 is also set, in which case it defaults to the appropriate
654 value for that platform.
655 Typically, one only needs to set
659 Builds under directory
661 are also influenced by defining one or more of the following symbols,
666 .Bl -tag -width ".Va -DNO_KERNELCONFIG"
667 .It Va LOADER_DEFAULT_INTERP
668 Defines what interpreter the default loader program will have.
674 This creates the default link for
676 to the loader with that interpreter.
677 It also determines what interpreter is compiled into
680 If set, the build targets that clean parts of the object tree use the
686 If set, no object tree files are cleaned at all.
687 This is the default when
701 is set no kernel objects are cleaned either.
703 If set, the build process does not run the DTrace CTF conversion tools
706 If set, the build does not descend into the
708 subdirectory (i.e., manual pages, locale data files, timezone data files and
711 files will not be rebuild from their sources).
712 .It Va NO_KERNELCLEAN
713 If set, the build process does not run
718 .It Va NO_KERNELCONFIG
719 If set, the build process does not run
725 If set, the build process does not run
731 If set, the update process does not update the source of the
733 documentation as part of the
737 If set, the libraries phase will be skipped.
739 If set, no object directories will be created.
740 This should only be used if object directories were created in a
741 previous build and no new directories are connected.
742 .It Va NO_PORTSUPDATE
743 If set, the update process does not update the Ports tree as part of the
747 If set, the update process does not update the www tree as part of the
751 If set, the build target
756 and will skip most bootstrap phases.
757 It will only bootstrap libraries and build all of userland.
758 This option should be used only when it is known that none of the bootstrap
759 needs changed and that no new directories have been connected to the build.
762 Builds under directory
764 are influenced by the following
767 .Bl -tag -width ".Va DOC_LANG"
769 If set, restricts the documentation build to the language subdirectories
770 specified as its content.
771 The default action is to build documentation for all languages.
776 and related targets are influenced by the following
779 .Bl -tag -width ".Va MAKE_JUST_KERNELS"
781 Pass the value of this variable to each
783 invocation used to build worlds and kernels.
784 This can be used to enable multiple jobs within a single architecture's build
785 while still building each architecture serially.
786 .It Va MAKE_JUST_KERNELS
787 Only build kernels for each supported architecture.
788 .It Va MAKE_JUST_WORLDS
789 Only build worlds for each supported architecture.
790 .It Va WITHOUT_WORLDS
791 Only build kernels for each supported architecture.
792 .It Va WITHOUT_KERNELS
793 Only build worlds for each supported architecture.
794 .It Va UNIVERSE_TARGET
795 Execute the specified
797 target for each supported architecture instead of the default action of
798 building a world and one or more kernels.
799 This variable implies
800 .Va WITHOUT_KERNELS .
802 Only build the listed targets instead of each supported architecture.
804 In addition to the supported architectures, build the semi-supported
806 A semi-supported architecture has build support in the
808 tree, but receives significantly less testing and is generally for
809 fringe uses that do not have a wide appeal.
812 .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
813 .It Pa /usr/doc/Makefile
814 .It Pa /usr/doc/share/mk/doc.project.mk
815 .It Pa /usr/ports/Mk/bsd.port.mk
816 .It Pa /usr/ports/Mk/bsd.sites.mk
817 .It Pa /usr/share/examples/etc/make.conf
818 .It Pa /usr/src/Makefile
819 .It Pa /usr/src/Makefile.inc1
824 method of updating your system from the latest sources, please see the
829 The following sequence of commands can be used to cross-build the
830 system for the armv6 architecture on an amd64 host:
831 .Bd -literal -offset indent
833 make TARGET_ARCH=armv6 buildworld buildkernel
834 make TARGET_ARCH=armv6 DESTDIR=/clients/arm installworld installkernel
839 manpage first appeared in
859 .An Mike W. Meyer Aq Mt mwm@mired.org
projects / FreeBSD / FreeBSD.git / blob