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
44 .Po installed from packages 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 issues the
73 command recursively in all subdirectories.
74 With no target specified, the items in the directories are built
75 and no further action is taken.
77 A source tree is allowed to be read-only.
80 objects are usually built in a separate object directory hierarchy
81 specified by the environment variable
82 .Va MAKEOBJDIRPREFIX ,
88 The canonical object directory is described in the documentation for the
92 The build may be controlled by defining
94 variables described in the
96 section below, and by the variables documented in
99 The default components included in the build are specified in the file
102 To override the default file, include the SRCCONF option in the make steps,
103 pointing to a custom src.conf file.
104 For more information see
107 The following list provides the names and actions for the targets
108 supported by the build system:
109 .Bl -tag -width ".Cm cleandepend"
111 Run Clang static analyzer against all objects and present output on stdout.
113 Run tests for a given subdirectory.
114 The default directory used is
116 but the check directory can be changed with
121 test suite on installed world.
123 Remove any files created during the build process.
126 .Pa ${.OBJDIR}/${DEPENDFILE}*
127 files generated by prior
133 Remove the canonical object directory if it exists, or perform
134 actions equivalent to
135 .Dq Li "make clean cleandepend"
137 This target will also remove an
143 It is advisable to run
144 .Dq Li "make cleandir"
145 twice: the first invocation will remove the canonical object directory
146 and the second one will clean up
149 Generate a list of build dependencies in file
150 .Pa ${.OBJDIR}/${DEPENDFILE} .
151 Per-object dependencies are generated at build time and stored in
152 .Pa ${.OBJDIR}/${DEPENDFILE}.${OBJ} .
154 Install the results of the build to the appropriate location in the
155 installation directory hierarchy specified in variable
158 Create the canonical object directory associated with the current
161 Create a symbolic link to the canonical object directory in
164 Generate a tags file using the program specified in the
168 The build system supports
174 The other supported targets under directory
177 .Bl -tag -width ".Cm distributeworld"
179 Spawn an interactive shell with environment variables set up for
180 building the system or individual components.
181 For cross-building the target architecture needs to be specified with
188 This target is only useful after a complete toolchain (including
189 the compiler, linker, assembler, headers and libraries) has been
194 Build everything but the kernel, configure files in
198 The object directory can be changed from the default
204 The actual build location prefix used
206 .Va WITH_UNIFIED_OBJDIR
210 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH}
213 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
214 for native builds, and
215 .Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}${.CURDIR}
216 for cross builds and native builds with variable
217 .Va CROSS_BUILD_TESTING
220 Attempt to clean up targets built by a preceding
222 or similar step built from this source directory.
225 .Va WITH_UNIFIED_OBJDIR
226 is enabled, attempt to clean up targets built by a preceding
229 or similar step, for any architecture built from this source directory.
230 .It Cm distributeworld
231 Distribute everything compiled by a preceding
234 Files are placed in the directory hierarchy specified by
238 This target is used while building a release; see
241 This target builds a cross-toolchain for the given
245 as well as a select list of static userland tools for the host system.
246 This is intended to be used in a jail where QEMU is used to improve
247 performance by avoiding emulating binaries that do not need to be emulated.
252 .It Cm native-xtools-install
253 Installs the results to
254 .Pa ${DESTDIR}/${NXTP}
264 Archive the results of
265 .Cm distributeworld ,
266 placing the results in
268 This target is used while building a release; see
271 Install everything built by a preceding
273 step into the directory hierarchy pointed to by
278 If installing onto an NFS file system and running
282 option, make sure that
284 is running on both client and server.
287 on how to make it start at boot time.
289 Create the build toolchain needed to build the rest of the system.
290 For cross-architecture builds, this step creates a cross-toolchain.
292 For each architecture,
297 for all kernels for that architecture,
300 This command takes a long time.
306 defined so only the kernels for each architecture are built.
312 defined so only the worlds for each architecture are built.
314 Print a list of supported
318 pairs for world and kernel targets.
320 Execute the same targets as
322 In addition print a summary of all failed targets at the end and
323 exit with an error if there were any.
325 Create a build toolchain for each architecture supported by the build system.
327 Builds and installs a cross-toolchain and sysroot for the given
331 The sysroot contains target library and headers.
332 The target is an alias for
336 The location of the files installed can be controlled with
338 The target location in
341 .Pa ${DESTDIR}/${XDTP}
349 .Pa ${TARGET_ARCH}-freebsd .
355 Installs the files for the
359 Installs autoconf-style symlinks to
360 .Pa ${DESTDIR}/usr/bin
361 pointing into the xdev toolchain in
362 .Pa ${DESTDIR}/${XDTP} .
365 Kernel specific build targets in
368 .Bl -tag -width ".Cm distributekernel"
370 Rebuild the kernel and the kernel modules.
371 The object directory can be changed from the default
378 Install the kernel and the kernel modules to directory
379 .Pa ${DESTDIR}/boot/kernel ,
380 renaming any pre-existing directory with this name to
382 if it contained the currently running kernel.
383 The target directory under
385 may be modified using the
391 .It Cm distributekernel
392 Install the kernel to the directory
393 .Pa ${DISTDIR}/kernel/boot/kernel .
394 This target is used while building a release; see
397 Archive the results of
398 .Cm distributekernel ,
399 placing the results in
401 This target is used while building a release; see
408 .It Cm kernel-toolchain
409 Rebuild the tools needed for kernel compilation.
410 Use this if you did not do a
413 .It Cm reinstallkernel
414 Reinstall the kernel and the kernel modules, overwriting the contents
415 of the target directory.
418 target, the target directory can be specified using the
424 Convenience targets for cleaning up the install destination directory
428 .Bl -tag -width ".Cm delete-old-libs"
430 Print a list of old files and directories in the system.
432 Delete obsolete base system files and directories interactively.
434 .Li -DBATCH_DELETE_OLD_FILES
435 is specified at the command line, the delete operation will be
442 should be set as with
443 .Dq Li "make installworld" .
444 .It Cm delete-old-libs
445 Delete obsolete base system libraries interactively.
446 This target should only be used if no third party software uses these
449 .Li -DBATCH_DELETE_OLD_FILES
450 is specified at the command line, the delete operation will be
457 should be set as with
458 .Dq Li "make installworld" .
461 Variables that influence all builds include:
462 .Bl -tag -width ".Va MAKEOBJDIRPREFIX"
464 Defines a set of debugging flags that will be used to build all userland
473 targets install binaries from the current
476 so that debugging information is retained in the installed binaries.
478 The directory hierarchy prefix where built objects will be installed.
481 defaults to the empty string.
482 .It Va MAKEOBJDIRPREFIX
483 Defines the prefix for directory names in the tree of built objects.
487 This variable should only be set in the environment or
488 .Pa /etc/src-env.conf
494 .It Va WITHOUT_WERROR
495 If defined, compiler warnings will not cause the build to halt,
496 even if the makefile says otherwise.
498 If defined, the build process will run the DTrace CTF conversion
499 tools on built objects.
502 Additionally, builds in
504 are influenced by the following
507 .Bl -tag -width ".Va SUBDIR_OVERRIDE"
509 Overrides which kernel to build and install for the various kernel
514 Overrides the directory in which
516 and any files included by
520 .Pa sys/${ARCH}/conf .
522 If set, the build target
526 .Va NO_KERNELCONFIG ,
529 When set to a value other than
533 is set to the value of
536 If set, this variable supplies a list of additional directories relative to
537 the root of the source tree to build as part of the
540 The directories are built in parallel with each other,
541 and with the base system directories.
544 directive at the beginning of the
546 list to ensure all base system directories are built first.
548 may also be used as needed elsewhere within the list.
550 If set, this variable supplies a list of additional tools that are used by the
555 .It Va LOCAL_LIB_DIRS
556 If set, this variable supplies a list of additional directories relative to
557 the root of the source tree to build as part of the
560 The directories are built in parallel with each other,
561 and with the base system libraries.
564 directive at the beginning of the
566 list to ensure all base system libraries are built first.
568 may also be used as needed elsewhere within the list.
570 If set, this variable supplies a list of additional mtrees relative to the
571 root of the source tree to use as part of the
574 .It Va LOCAL_LEGACY_DIRS
575 If set, this variable supplies a list of additional directories relative to
576 the root of the source tree to build as part of the
579 .It Va LOCAL_BSTOOL_DIRS
580 If set, this variable supplies a list of additional directories relative to
581 the root of the source tree to build as part of the
584 .It Va LOCAL_TOOL_DIRS
585 If set, this variable supplies a list of additional directories relative to
586 the root of the source tree to build as part of the
589 .It Va LOCAL_XTOOL_DIRS
590 If set, this variable supplies a list of additional directories relative to
591 the root of the source tree to build as part of the
595 A list of ports with kernel modules that should be built and installed
601 .Bd -literal -offset indent
602 make PORTS_MODULES=emulators/virtualbox-ose-kmod kernel
605 Specify a file to override the default
607 The src.conf file controls the components to build.
611 Command to use at install time when stripping binaries.
612 Be sure to add any additional tools required to run
617 variable before running the
625 .It Va SUBDIR_OVERRIDE
626 Override the default list of sub-directories and only build the
627 sub-directory named in this variable.
630 then all libraries and includes, and some of the build tools will still build
636 will only build the specified directory as was done historically.
639 it is necesarry to override
641 with any custom directories containing libraries.
642 This allows building a subset of the system in the same way as
644 does using its sysroot handling.
645 This variable can also be useful when debugging failed builds.
646 .Bd -literal -offset indent
647 make some-target SUBDIR_OVERRIDE=foo/bar
650 Specify the location of the kernel source to override the default
652 The kernel source is located in the
654 subdirectory of the source tree checked out from the
658 The target hardware platform.
659 This is analogous to the
662 This is necessary to cross-build some target architectures.
663 For example, cross-building for ARM64 machines requires
664 .Va TARGET_ARCH Ns = Ns Li aarch64
666 .Va TARGET Ns = Ns Li arm64 .
669 defaults to the current hardware platform, unless
671 is also set, in which case it defaults to the appropriate
672 value for that architecture.
674 The target machine processor architecture.
675 This is analogous to the
678 Set this to cross-build for a different architecture.
681 defaults to the current machine architecture, unless
683 is also set, in which case it defaults to the appropriate
684 value for that platform.
685 Typically, one only needs to set
689 Builds under directory
691 are also influenced by defining one or more of the following symbols,
696 .Bl -tag -width ".Va -DNO_KERNELCONFIG"
697 .It Va LOADER_DEFAULT_INTERP
698 Defines what interpreter the default loader program will have.
704 This creates the default link for
706 to the loader with that interpreter.
707 It also determines what interpreter is compiled into
710 If set, the build targets that clean parts of the object tree use the
716 If set, no object tree files are cleaned at all.
717 This is the default when
731 is set no kernel objects are cleaned either.
733 If set, the build process does not run the DTrace CTF conversion tools
736 If set, the build does not descend into the
738 subdirectory (i.e., manual pages, locale data files, timezone data files and
741 files will not be rebuild from their sources).
742 .It Va NO_KERNELCLEAN
743 If set, the build process does not run
748 .It Va NO_KERNELCONFIG
749 If set, the build process does not run
755 If set, the build process does not run
761 If set, the libraries phase will be skipped.
763 If set, no object directories will be created.
764 This should only be used if object directories were created in a
765 previous build and no new directories are connected.
767 If set, the build target
772 and will skip most bootstrap phases.
773 It will only bootstrap libraries and build all of userland.
774 This option should be used only when it is known that none of the bootstrap
775 needs changed and that no new directories have been connected to the build.
778 Builds under directory
780 are influenced by the following
783 .Bl -tag -width ".Va DOC_LANG"
785 If set, restricts the documentation build to the language subdirectories
786 specified as its content.
787 The default action is to build documentation for all languages.
792 and related targets are influenced by the following
795 .Bl -tag -width ".Va MAKE_JUST_KERNELS"
797 Pass the value of this variable to each
799 invocation used to build worlds and kernels.
800 This can be used to enable multiple jobs within a single architecture's build
801 while still building each architecture serially.
802 .It Va MAKE_JUST_KERNELS
803 Only build kernels for each supported architecture.
804 .It Va MAKE_JUST_WORLDS
805 Only build worlds for each supported architecture.
806 .It Va WITHOUT_WORLDS
807 Only build kernels for each supported architecture.
808 .It Va WITHOUT_KERNELS
809 Only build worlds for each supported architecture.
810 .It Va UNIVERSE_TARGET
811 Execute the specified
813 target for each supported architecture instead of the default action of
814 building a world and one or more kernels.
815 This variable implies
816 .Va WITHOUT_KERNELS .
818 Only build the listed targets instead of each supported architecture.
820 In addition to the supported architectures, build the semi-supported
822 A semi-supported architecture has build support in the
824 tree, but receives significantly less testing and is generally for
825 fringe uses that do not have a wide appeal.
828 .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
829 .It Pa /usr/doc/Makefile
830 .It Pa /usr/doc/share/mk/doc.project.mk
831 .It Pa /usr/ports/Mk/bsd.port.mk
832 .It Pa /usr/ports/Mk/bsd.sites.mk
833 .It Pa /usr/share/examples/etc/make.conf
834 .It Pa /usr/src/Makefile
835 .It Pa /usr/src/Makefile.inc1
840 method of updating your system from the latest sources, please see the
845 The following sequence of commands can be used to cross-build the
846 system for the armv6 architecture on an amd64 host:
847 .Bd -literal -offset indent
849 make TARGET_ARCH=armv6 buildworld buildkernel
850 make TARGET_ARCH=armv6 DESTDIR=/clients/arm installworld installkernel
855 manpage first appeared in
874 .An Mike W. Meyer Aq Mt mwm@mired.org
projects / FreeBSD / FreeBSD.git / blob