aboutsummaryrefslogtreecommitdiff
path: root/share/man/man7/build.7
blob: d5036daf87b590ce535bd44f33ee97f9e59e2e53 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
.\" Copyright (c) 2000
.\"	Mike W. Meyer
.\"
.\" 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 AUTHOR ``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 AUTHOR 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 May 11, 2017
.Dt BUILD 7
.Os
.Sh NAME
.Nm build
.Nd information on how to build the system
.Sh DESCRIPTION
The sources for the
.Fx
system and its applications are contained in three different directories,
normally
.Pa /usr/src ,
.Pa /usr/doc ,
and
.Pa /usr/ports .
These directories may be initially empty or non-existent until updated with
.Xr svn 1
or
.Xr portsnap 8 .
Directory
.Pa /usr/src
contains the
.Dq "base system"
sources, which is loosely defined as the things required to rebuild
the system to a useful state.
Directory
.Pa /usr/doc
contains the source for the system documentation, excluding the manual
pages.
Directory
.Pa /usr/ports
contains a tree that provides a consistent interface for building and
installing third party applications.
For more information about the ports build process, see
.Xr ports 7 .
.Pp
The
.Xr make 1
command is used in each of these directories to build and install the
things in that directory.
Issuing the
.Xr make 1
command in any directory or
subdirectory of those directories has the same effect as issuing the
same command in all subdirectories of that directory.
With no target specified, the things in that directory are just built.
.Pp
A source tree is allowed to be read-only.
As described in
.Xr make 1 ,
objects are usually built in a separate object directory hierarchy
specified by the environment variable
.Va MAKEOBJDIRPREFIX ,
or under
.Pa /usr/obj
if variable
.Va MAKEOBJDIRPREFIX
is not set.
For a given source directory, its canonical object directory
would be
.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
if
.Xr make 1
variable
.Va MAKEOBJDIRPREFIX
is set, or
.Pa /usr/obj${.CURDIR}
if this variable is not set.
Cross-builds set the object directory as described in the
documentation for the
.Cm buildworld
target below.
.Pp
The build may be controlled by defining
.Xr make 1
variables described in the
.Sx ENVIRONMENT
section below, and by the variables documented in
.Xr make.conf 5 .
.Pp
The following list provides the names and actions for the targets
supported by the build system:
.Bl -tag -width ".Cm cleandepend"
.It Cm analyze
Run Clang static analyzer against all objects and present output on stdout.
.It Cm check
Run tests for a given subdirectory.
The default directory used is
.Pa ${.OBJDIR} ,
but the check directory can be changed with
.Pa ${CHECKDIR} .
.It Cm checkworld
Run the
.Fx
test suite on installed world.
.It Cm clean
Remove any files created during the build process.
.It Cm cleandepend
Remove the
.Pa ${.OBJDIR}/${DEPENDFILE}*
files generated by prior
.Dq Li "make"
and
.Dq Li "make depend"
steps.
.It Cm cleandir
Remove the canonical object directory if it exists, or perform
actions equivalent to
.Dq Li "make clean cleandepend"
if it does not.
This target will also remove an
.Pa obj
link in
.Pa ${.CURDIR}
if that exists.
.Pp
It is advisable to run
.Dq Li "make cleandir"
twice: the first invocation will remove the canonical object directory
and the second one will clean up
.Pa ${.CURDIR} .
.It Cm depend
Generate a list of build dependencies in file
.Pa ${.OBJDIR}/${DEPENDFILE} .
Per-object dependencies are generated at build time and stored in
.Pa ${.OBJDIR}/${DEPENDFILE}.${OBJ} .
.It Cm install
Install the results of the build to the appropriate location in the
installation directory hierarchy specified in variable
.Va DESTDIR .
.It Cm obj
Create the canonical object directory associated with the current
directory.
.It Cm objlink
Create a symbolic link to the canonical object directory in
.Pa ${.CURDIR} .
.It Cm tags
Generate a tags file using the program specified in the
.Xr make 1
variable
.Va CTAGS .
The build system supports
.Xr ctags 1
and
.Nm "GNU Global" .
.El
.Pp
The other supported targets under directory
.Pa /usr/src
are:
.Bl -tag -width ".Cm distributeworld"
.It Cm buildenv
Spawn an interactive shell with environment variables set up for
cross-building the system.
The target architecture needs to be specified with
.Xr make 1
variables
.Va TARGET_ARCH
and
.Va TARGET .
.Pp
This target is only useful after a complete cross-toolchain including
the compiler, linker, assembler, headers and libraries has been
built; see the
.Cm toolchain
target below.
.It Cm buildworld
Build everything but the kernel, configure files in
.Pa etc ,
and
.Pa release .
The object directory can be changed from the default
.Pa /usr/obj
by setting the
.Pa MAKEOBJDIRPREFIX
.Xr make 1
variable.
The actual build location prefix used is
.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
for native builds, and
.Pa ${MAKEOBJDIRPREFIX}/${TARGET}${.CURDIR}
for cross builds and native builds with variable
.Va CROSS_BUILD_TESTING
set.
.It Cm cleanworld
Attempt to clean up targets built by a preceding
.Cm buildworld
step.
.It Cm distributeworld
Distribute everything compiled by a preceding
.Cm buildworld
step.
Files are placed in the directory hierarchy specified by
.Xr make 1
variable
.Va DISTDIR .
This target is used while building a release; see
.Xr release 7 .
.It Cm packageworld
Archive the results of
.Cm distributeworld ,
placing the results in
.Va DISTDIR .
This target is used while building a release; see
.Xr release 7 .
.It Cm installworld
Install everything built by a preceding
.Cm buildworld
step into the directory hierarchy pointed to by
.Xr make 1
variable
.Va DESTDIR .
.Pp
If installing onto an NFS file system and running
.Xr make 1
with the
.Fl j
option, make sure that
.Xr rpc.lockd 8
is running on both client and server.
See
.Xr rc.conf 5
on how to make it start at boot time.
.It Cm toolchain
Create the build toolchain needed to build the rest of the system.
For cross-architecture builds, this step creates a cross-toolchain.
.It Cm universe
For each architecture,
execute a
.Cm buildworld
followed by a
.Cm buildkernel
for all kernels for that architecture,
including
.Pa LINT .
This command takes a long time.
.It Cm update
Get updated sources as configured in
.Xr make.conf 5 .
.It Cm targets
Print a list of supported
.Va TARGET
/
.Va TARGET_ARCH
pairs for world and kernel targets.
.It Cm tinderbox
Execute the same targets as
.Cm universe .
In addition print a summary of all failed targets at the end and
exit with an error if there were any.
.It Cm toolchains
Create a build toolchain for each architecture supported by the build system.
.El
.Pp
Kernel specific build targets in
.Pa /usr/src
are:
.Bl -tag -width ".Cm distributekernel"
.It Cm buildkernel
Rebuild the kernel and the kernel modules.
The object directory can be changed from the default
.Pa /usr/obj
by setting the
.Pa MAKEOBJDIRPREFIX
.Xr make 1
variable.
.It Cm installkernel
Install the kernel and the kernel modules to directory
.Pa ${DESTDIR}/boot/kernel ,
renaming any pre-existing directory with this name to
.Pa kernel.old
if it contained the currently running kernel.
The target directory under
.Pa ${DESTDIR}
may be modified using the
.Va INSTKERNNAME
and
.Va KODIR
.Xr make 1
variables.
.It Cm distributekernel
Install the kernel to the directory
.Pa ${DISTDIR}/kernel/boot/kernel .
This target is used while building a release; see
.Xr release 7 .
.It Cm packagekernel
Archive the results of
.Cm distributekernel ,
placing the results in
.Va DISTDIR .
This target is used while building a release; see
.Xr release 7 .
.It Cm kernel
Equivalent to
.Cm buildkernel
followed by
.Cm installkernel
.It Cm kernel-toolchain
Rebuild the tools needed for kernel compilation.
Use this if you did not do a
.Cm buildworld
first.
.It Cm reinstallkernel
Reinstall the kernel and the kernel modules, overwriting the contents
of the target directory.
As with the
.Cm installkernel
target, the target directory can be specified using the
.Xr make 1
variable
.Va INSTKERNNAME .
.El
.Pp
Convenience targets for cleaning up the install destination directory
denoted by variable
.Va DESTDIR
include:
.Bl -tag -width ".Cm delete-old-libs"
.It Cm check-old
Print a list of old files and directories in the system.
.It Cm delete-old
Delete obsolete base system files and directories interactively.
When
.Li -DBATCH_DELETE_OLD_FILES
is specified at the command line, the delete operation will be
non-interactive.
The variables
.Va DESTDIR ,
.Va TARGET_ARCH
and
.Va TARGET
should be set as with
.Dq Li "make installworld" .
.It Cm delete-old-libs
Delete obsolete base system libraries interactively.
This target should only be used if no third party software uses these
libraries.
When
.Li -DBATCH_DELETE_OLD_FILES
is specified at the command line, the delete operation will be
non-interactive.
The variables
.Va DESTDIR ,
.Va TARGET_ARCH
and
.Va TARGET
should be set as with
.Dq Li "make installworld" .
.El
.Sh ENVIRONMENT
Variables that influence all builds include:
.Bl -tag -width ".Va MAKEOBJDIRPREFIX"
.It Va DEBUG_FLAGS
Defines a set of debugging flags that will be used to build all userland
binaries under
.Pa /usr/src .
When
.Va DEBUG_FLAGS
is defined, the
.Cm install
and
.Cm installworld
targets install binaries from the current
.Va MAKEOBJDIRPREFIX
without stripping,
so that debugging information is retained in the installed binaries.
.It Va DESTDIR
The directory hierarchy prefix where built objects will be installed.
If not set,
.Va DESTDIR
defaults to the empty string.
.It Va MAKEOBJDIRPREFIX
Defines the prefix for directory names in the tree of built objects.
Defaults to
.Pa /usr/obj
if not defined.
This variable should only be set in the environment and not via
.Pa /etc/make.conf
or the command line.
.It Va NO_WERROR
If defined, compiler warnings will not cause the build to halt,
even if the makefile says otherwise.
.It Va WITH_CTF
If defined, the build process will run the DTrace CTF conversion
tools on built objects.
.El
.Pp
Additionally, builds in
.Pa /usr/src
are influenced by the following
.Xr make 1
variables:
.Bl -tag -width ".Va SUBDIR_OVERRIDE"
.It Va KERNCONF
Overrides which kernel to build and install for the various kernel
make targets.
It defaults to
.Cm GENERIC .
.It Va KERNFAST
If set, the build target
.Cm buildkernel
defaults to setting
.Va NO_KERNELCLEAN ,
.Va NO_KERNELCONFIG ,
and
.Va NO_KERNELOBJ .
When set to a value other than
.Cm 1
then
.Va KERNCONF
is set to the value of
.Va KERNFAST .
.It Va LOCAL_DIRS
If set, this variable supplies a list of additional directories relative to
the root of the source tree to build as part of the
.Cm everything
target.
.It Va LOCAL_ITOOLS
If set, this variable supplies a list of additional tools that are used by the
.Cm installworld
and
.Cm distributeworld
targets.
.It Va LOCAL_LIB_DIRS
If set, this variable supplies a list of additional directories relative to
the root of the source tree to build as part of the
.Cm libraries
target.
.It Va LOCAL_MTREE
If set, this variable supplies a list of additional mtrees relative to the
root of the source tree to use as part of the
.Cm hierarchy
target.
.It Va LOCAL_TOOL_DIRS
If set, this variable supplies a list of additional directories relative to
the root of the source tree to build as part of the
.Cm build-tools
target.
.It Va LOCAL_XTOOL_DIRS
If set, this variable supplies a list of additional directories relative to
the root of the source tree to build as part of the
.Cm cross-tools
target.
.It Va PORTS_MODULES
A list of ports with kernel modules that should be built and installed
as part of the
.Cm buildkernel
and
.Cm installkernel
process.
.Bd -literal -offset indent
make PORTS_MODULES=emulators/kqemu-kmod kernel
.Ed
.It Va STRIPBIN
Command to use at install time when stripping binaries.
Be sure to add any additional tools required to run
.Va STRIPBIN
to the
.Va LOCAL_ITOOLS
.Xr make 1
variable before running the
.Cm distributeworld
or
.Cm installworld
targets.
See
.Xr install 1
for more details.
.It Va SUBDIR_OVERRIDE
Override the default list of sub-directories and only build the
sub-directory named in this variable.
If combined with
.Cm buildworld
then all libraries and includes, and some of the build tools will still build
as well.
Specifying
.Cm -DNO_LIBS ,
and
.Cm -DWORLDFAST
will only build the specified directory as was done historically.
When combined with
.Cm buildworld
it is necesarry to override
.Va LOCAL_LIB_DIRS
with any custom directories containing libraries.
This allows building a subset of the system in the same way as
.Cm buildworld
does using its sysroot handling.
This variable can also be useful when debugging failed builds.
.Bd -literal -offset indent
make some-target SUBDIR_OVERRIDE=foo/bar
.Ed
.It Va TARGET
The target hardware platform.
This is analogous to the
.Dq Nm uname Fl m
output.
This is necessary to cross-build some target architectures.
For example, cross-building for ARM64 machines requires
.Va TARGET_ARCH Ns = Ns Li aarch64
and
.Va TARGET Ns = Ns Li arm64 .
If not set,
.Va TARGET
defaults to the current hardware platform, unless
.Va TARGET_ARCH
is also set, in which case it defaults to the appropriate
value for that architecture.
.It Va TARGET_ARCH
The target machine processor architecture.
This is analogous to the
.Dq Nm uname Fl p
output.
Set this to cross-build for a different architecture.
If not set,
.Va TARGET_ARCH
defaults to the current machine architecture, unless
.Va TARGET
is also set, in which case it defaults to the appropriate
value for that platform.
Typically, one only needs to set
.Va TARGET .
.El
.Pp
Builds under directory
.Pa /usr/src
are also influenced by defining one or more of the following symbols,
using the
.Fl D
option of
.Xr make 1 :
.Bl -tag -width ".Va -DNO_KERNELCONFIG"
.It Va NO_CLEANDIR
If set, the build targets that clean parts of the object tree use the
equivalent of
.Dq make clean
instead of
.Dq make cleandir .
.It Va NO_CLEAN
If set, no object tree files are cleaned at all.
This is the default when
.Va WITH_META_MODE
is used with
.Xr filemon 4
loaded.
See
.Xr src.conf 5
for more details.
Setting
.Va NO_CLEAN
implies
.Va NO_KERNELCLEAN ,
so when
.Va NO_CLEAN
is set no kernel objects are cleaned either.
.It Va NO_CTF
If set, the build process does not run the DTrace CTF conversion tools
on built objects.
.It Va NO_SHARE
If set, the build does not descend into the
.Pa /usr/src/share
subdirectory (i.e., manual pages, locale data files, timezone data files and
other
.Pa /usr/src/share
files will not be rebuild from their sources).
.It Va NO_KERNELCLEAN
If set, the build process does not run
.Dq make clean
as part of the
.Cm buildkernel
target.
.It Va NO_KERNELCONFIG
If set, the build process does not run
.Xr config 8
as part of the
.Cm buildkernel
target.
.It Va NO_KERNELOBJ
If set, the build process does not run
.Dq make obj
as part of the
.Cm buildkernel
target.
.It Va NO_DOCUPDATE
If set, the update process does not update the source of the
.Fx
documentation as part of the
.Dq make update
target.
.It Va NO_LIBS
If set, the libraries phase will be skipped.
.It Va NO_OBJ
If set, no object directories will be created.
This should only be used if object directories were created in a
previous build and no new directories are connected.
.It Va NO_PORTSUPDATE
If set, the update process does not update the Ports tree as part of the
.Dq make update
target.
.It Va NO_WWWUPDATE
If set, the update process does not update the www tree as part of the
.Dq make update
target.
.It Va WORLDFAST
If set, the build target
.Cm buildworld
defaults to setting
.Va NO_CLEAN ,
.Va NO_OBJ ,
and will skip most bootstrap phases.
It will only bootstrap libraries and build all of userland.
This option should be used only when it is known that none of the bootstrap
needs changed and that no new directories have been connected to the build.
.El
.Pp
Builds under directory
.Pa /usr/doc
are influenced by the following
.Xr make 1
variables:
.Bl -tag -width ".Va DOC_LANG"
.It Va DOC_LANG
If set, restricts the documentation build to the language subdirectories
specified as its content.
The default action is to build documentation for all languages.
.El
.Pp
Builds using the
.Cm universe
target are influenced by the following
.Xr make 1
variables:
.Bl -tag -width ".Va MAKE_JUST_KERNELS"
.It Va JFLAG
Pass the value of this variable to each
.Xr make 1
invocation used to build worlds and kernels.
This can be used to enable multiple jobs within a single architecture's build
while still building each architecture serially.
.It Va MAKE_JUST_KERNELS
Only build kernels for each supported architecture.
.It Va MAKE_JUST_WORLDS
Only build worlds for each supported architecture.
.It Va UNIVERSE_TARGET
Execute the specified
.Xr make 1
target for each supported architecture instead of the default action of
building a world and one or more kernels.
.El
.Sh FILES
.Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
.It Pa /usr/doc/Makefile
.It Pa /usr/doc/share/mk/doc.project.mk
.It Pa /usr/ports/Mk/bsd.port.mk
.It Pa /usr/ports/Mk/bsd.sites.mk
.It Pa /usr/share/examples/etc/make.conf
.It Pa /usr/src/Makefile
.It Pa /usr/src/Makefile.inc1
.El
.Sh EXAMPLES
For an
.Dq approved
method of updating your system from the latest sources, please see the
.Sx COMMON ITEMS
section in
.Pa src/UPDATING .
.Pp
The following sequence of commands can be used to cross-build the
system for the armv6 architecture on an amd64 host:
.Bd -literal -offset indent
cd /usr/src
make TARGET_ARCH=armv6 buildworld buildkernel
make TARGET_ARCH=armv6 DESTDIR=/clients/arm64 installworld installkernel
.Ed
.Sh SEE ALSO
.Xr cc 1 ,
.Xr install 1 ,
.Xr make 1 ,
.Xr svn 1 ,
.Xr make.conf 5 ,
.Xr src.conf 5 ,
.Xr arch 7 ,
.Xr ports 7 ,
.Xr release 7 ,
.Xr tests 7 ,
.Xr config 8 ,
.Xr mergemaster 8 ,
.Xr portsnap 8 ,
.Xr reboot 8 ,
.Xr shutdown 8
.Sh AUTHORS
.An Mike W. Meyer Aq Mt mwm@mired.org