forked from tworaz/src
/
BUILDING
1005 lines (762 loc) · 47.6 KB
/
BUILDING
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
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
BUILDING(8) NetBSD System Manager's Manual BUILDING(8)
NAME
BUILDING -- Procedure for building NetBSD from source code.
REQUIREMENTS
NetBSD is designed to be buildable on most POSIX-compliant host systems.
The basic build procedure is the same whether compiling natively (on the
same NetBSD architecture) or cross compiling (on another architecture or
OS).
This source tree contains a special subtree, ``tools'', which uses the
host system to create a build toolchain for the target architecture. The
host system must have at least C and C++ compilers in order to create the
toolchain (make is not required); all other tools are created as part of
the NetBSD build process. (See the environment variables section below
if you need to override or manually select your compilers.)
FILES
Source tree layout
doc/BUILDING.mdoc
This document (in -mdoc troff format; the original copy).
BUILDING This document (in plaintext).
tools/compat/README
Special notes for cross-hosting a NetBSD build on non-
NetBSD platforms.
Makefile The main Makefile for NetBSD; should only be run for
native builds with an appropriately up-to-date version of
NetBSD make(1). (For building from out-of-date systems or
on a non-native host, see the build.sh shell script.)
UPDATING Special notes for updating from an earlier revision of
NetBSD. It is important to read this file before every
build of an updated source tree.
build.sh Bourne-compatible shell script used for building the host
build tools and the NetBSD system from scratch. Can be
used for both native and cross builds, and should be used
instead of make(1) for any source tree that is updated and
recompiled regularly.
crypto/dist/, dist/, gnu/dist/
Sources imported verbatim from third parties, without man-
gling the existing build structure. Other source trees in
bin through usr.sbin use the NetBSD make(1) ``reachover''
Makefile semantics when building these programs for a
native host.
distrib/, etc/
Sources for items used when making a full release snap-
shot, such as files installed in DESTDIR/etc on the desti-
nation system, boot media, and release notes.
tests/, regress/
Regression test harness. Can be cross-compiled, but only
run natively. tests/ uses the atf(7) test framework;
regress/ contains older tests that have not yet been
migrated to atf(7).
sys/ NetBSD kernel sources.
tools/ ``Reachover'' build structure for the host build tools.
This has a special method of determining out-of-date sta-
tus.
bin/ ... usr.sbin/
Sources to the NetBSD userland (non-kernel) programs. If
any of these directories are missing, they will be skipped
during the build.
x11/ ``Reachover'' build structure for X11R6; the source is in
X11SRCDIR.
Build tree layout
The NetBSD build tree is described in hier(7), and the release layout is
described in release(7).
CONFIGURATION
Environment variables
Several environment variables control the behaviour of NetBSD builds.
HOST_SH Path name to a shell available on the host system and
suitable for use during the build. The NetBSD build
system requires a modern Bourne-like shell with POSIX-
compliant features, and also requires support for the
``local'' keyword to declare local variables in shell
functions (which is a widely-implemented but non-stan-
dardised feature).
Depending on the host system, a suitable shell may be
/bin/sh, /usr/xpg4/bin/sh, /bin/ksh (provided it is a
variant of ksh that supports the ``local'' keyword,
such as ksh88, but not ksh93), or /usr/local/bin/bash.
Most parts of the build require HOST_SH to be an abso-
lute path; however, build.sh allows it to be a simple
command name, which will be converted to an absolute
path by searching the PATH.
HOST_CC Path name to C compiler used to create the toolchain.
HOST_CXX Path name to C++ compiler used to create the toolchain.
MACHINE Machine type, e.g., ``macppc''.
MACHINE_ARCH Machine architecture, e.g., ``powerpc''.
MAKE Path name to invoke make(1) as.
MAKEFLAGS Flags to invoke make(1) with. Note that build.sh
ignores the value of MAKEFLAGS passed in the environ-
ment, but allows MAKEFLAGS to be set via the -V option.
MAKEOBJDIR Directory to use as the .OBJDIR for the current direc-
tory. The value is subjected to variable expansion by
make(1). Typical usage is to set this variable to a
value involving the use of `${.CURDIR:S...}' or
`${.CURDIR:C...}', to derive the value of .OBJDIR from
the value of .CURDIR. Used only if MAKEOBJDIRPREFIX is
not defined. MAKEOBJDIR can be provided only in the
environment or via the -O flag of build.sh; it cannot
usefully be set inside a Makefile, including mk.conf or
${MAKECONF}.
MAKEOBJDIRPREFIX Top level directory of the object directory tree. The
value is subjected to variable expansion by make(1).
build.sh will create the ${MAKEOBJDIRPREFIX} directory
if necessary, but if make(1) is used without build.sh,
then rules in <bsd.obj.mk> will abort the build if the
${MAKEOBJDIRPREFIX} directory does not exist. If the
value is defined and valid, then ${MAKEOBJDIRPRE-
FIX}/${.CURDIR} is used as the .OBJDIR for the current
directory. The current directory may be read only.
MAKEOBJDIRPREFIX can be provided only in the environ-
ment or via the -M flag of build.sh; it cannot usefully
be set inside a Makefile, including mk.conf or
${MAKECONF}.
"make" variables
Several variables control the behavior of NetBSD builds. Unless other-
wise specified, these variables may be set in either the process environ-
ment or the make(1) configuration file specified by MAKECONF.
BUILDID Identifier for the build. The identifier will be appended to
object directory names, and can be consulted in the make(1)
configuration file in order to set additional build parame-
ters, such as compiler flags.
BUILDSEED GCC uses random numbers when compiling C++ code. This vari-
able seeds the gcc random number generator using the -fran-
dom-seed flag with this value. By default, it is set to
NetBSD-(majorversion). Using a fixed value causes C++ bina-
ries to be the same when built from the same sources, result-
ing in identical (reproducible) builds. Additional informa-
tion is available in the GCC documentation of -frandom-seed.
DESTDIR Directory to contain the built NetBSD system. If set, spe-
cial options are passed to the compilation tools to prevent
their default use of the host system's /usr/include,
/usr/lib, and so forth. This pathname must be an absolute
path, and should not end with a slash (/) character. (For
installation into the system's root directory, set DESTDIR to
an empty string, not to ``/''). The directory must reside on
a file system which supports long file names and hard links.
Default: Empty string if USETOOLS is ``yes''; unset other-
wise.
Note: build.sh will provide a default of destdir.MACHINE (in
the top-level .OBJDIR) unless run in `expert' mode.
MAKECONF The name of the make(1) configuration file. Only settable in
the process environment.
Default: ``/etc/mk.conf''
MAKEVERBOSE
Level of verbosity of status messages. Supported values:
0 No descriptive messages or commands executed by make(1)
are shown.
1 Brief messages are shown describing what is being done,
but the actual commands executed by make(1) are not dis-
played.
2 Descriptive messages are shown as above (prefixed with a
`#'), and ordinary commands performed by make(1) are
displayed.
3 In addition to the above, all commands performed by
make(1) are displayed, even if they would ordinarily
have been hidden through use of the ``@'' prefix in the
relevant makefile.
4 In addition to the above, commands executed by make(1)
are traced through use of the sh(1) ``-x'' flag.
Default: 2
MKCATPAGES Can be set to ``yes'' or ``no''. Indicates whether prefor-
matted plaintext manual pages will be created during a build.
Default: ``yes''
MKCRYPTO Can be set to ``yes'' or ``no''. Indicates whether crypto-
graphic code will be included in a build; provided for the
benefit of countries that do not allow strong cryptography.
Will not affect use of the standard low-security password
encryption system, crypt(3).
Default: ``yes''
MKDOC Can be set to ``yes'' or ``no''. Indicates whether system
documentation destined for DESTDIR/usr/share/doc will be
installed during a build.
Default: ``yes''
MKHTML Can be set to ``yes'' or ``no''. Indicates whether prefor-
matted HTML manual pages will be built and installed
Default: ``yes''
MKHOSTOBJ Can be set to ``yes'' or ``no''. If set to ``yes'', then for
programs intended to be run on the compile host, the name,
release, and architecture of the host operating system will
be suffixed to the name of the object directory created by
``make obj''. (This allows multiple host systems to compile
NetBSD for a single target.) If set to ``no'', then programs
built to be run on the compile host will use the same object
directory names as programs built to be run on the target.
Default: ``no''
MKINFO Can be set to ``yes'' or ``no''. Indicates whether GNU Info
files, used for the documentation for most of the compilation
tools, will be created and installed during a build.
Default: ``yes''
MKKMOD Can be set to ``yes'' or ``no''. Indicates whether kernel
modules are built and installed.
Default: ``yes''
MKLINT Can be set to ``yes'' or ``no''. Indicates whether lint(1)
will be run against portions of the NetBSD source code during
the build, and whether lint libraries will be installed into
DESTDIR/usr/libdata/lint.
Default: ``yes''
MKMAN Can be set to ``yes'' or ``no''. Indicates whether manual
pages will be installed during a build.
Default: ``yes''
MKNLS Can be set to ``yes'' or ``no''. Indicates whether Native
Language System locale zone files will be compiled and
installed during a build.
Default: ``yes''
MKOBJ Can be set to ``yes'' or ``no''. Indicates whether object
directories will be created when running ``make obj''. If
set to ``no'', then all built files will be located inside
the regular source tree.
Default: ``yes''
Note that setting MKOBJ to ``no'' is not recommended and may
cause problems when updating the tree with cvs(1).
MKPIC Can be set to ``yes'' or ``no''. Indicates whether shared
objects and libraries will be created and installed during a
build. If set to ``no'', the entire built system will be
statically linked.
Default: Platform dependent. As of this writing, all plat-
forms except sh3 default to ``yes''.
MKPICINSTALL
Can be set to ``yes'' or ``no''. Indicates whether the ar(1)
format libraries (lib*_pic.a), used to generate shared
libraries, are installed during a build.
Default: ``yes''
MKPROFILE Can be set to ``yes'' or ``no''. Indicates whether profiled
libraries (lib*_p.a) will be built and installed during a
build.
Default: ``yes''; however, some platforms turn off MKPROFILE
by default at times due to toolchain problems with profiled
code.
MKREPRO Can be set to ``yes'' or ``no''. Create reproducable builds.
This enables different switches to make two builds from the
same source tree result in the same build results.
Default: ``no''
MKSHARE Can be set to ``yes'' or ``no''. Indicates whether files
destined to reside in DESTDIR/usr/share will be built and
installed during a build. If set to ``no'', then all of
MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
``no'' unconditionally.
Default: ``yes''
MKSTRIPIDENT
Can be set to ``yes'' or ``no''. Indicates whether RCS IDs,
for use with ident(1), should be stripped from program bina-
ries and shared libraries.
Default: ``no''
MKUNPRIVED Can be set to ``yes'' or ``no''. Indicates whether an
unprivileged install will occur. The user, group, permis-
sions, and file flags, will not be set on the installed
items; instead the information will be appended to a file
called METALOG in DESTDIR. The contents of METALOG are used
during the generation of the distribution tar files to ensure
that the appropriate file ownership is stored.
Default: ``no''
MKUPDATE Can be set to ``yes'' or ``no''. Indicates whether all
install operations intended to write to DESTDIR will compare
file timestamps before installing, and skip the install phase
if the destination files are up-to-date. This also has
implications on full builds (see next subsection).
Default: ``no''
MKX11 Can be set to ``yes'' or ``no''. Indicates whether X11 is
built from X11SRCDIR.
Default: ``no''
TOOLDIR Directory to hold the host tools, once built. If specified,
must be an absolute path. This directory should be unique to
a given host system and NetBSD source tree. (However, multi-
ple targets may share the same TOOLDIR; the target-dependent
files have unique names.) If unset, a default based on the
uname(1) information of the host platform will be created in
the .OBJDIR of src.
Default: Unset.
USETOOLS Indicates whether the tools specified by TOOLDIR should be
used as part of a build in progress. Must be set to ``yes''
if cross-compiling.
yes Use the tools from TOOLDIR.
no Do not use the tools from TOOLDIR, but refuse to build
native compilation tool components that are version-
specific for that tool.
never Do not use the tools from TOOLDIR, even when building
native tool components. This is similar to the tradi-
tional NetBSD build method, but does not verify that
the compilation tools in use are up-to-date enough in
order to build the tree successfully. This may cause
build or runtime problems when building the whole
NetBSD source tree.
Default: ``yes'', unless TOOLCHAIN_MISSING is set to ``yes''.
USETOOLS is also set to ``no'' when using <bsd.*.mk> outside
the NetBSD source tree.
X11SRCDIR Directory containing the X11R6 source. If specified, must be
an absolute path. The main X11R6 source is found in
X11SRCDIR/xfree/xc.
Default: NETBSDRCDIR/../xsrc, if that exists; otherwise
/usr/xsrc.
X11FLAVOUR The style of X11 cross-built, set to either ``Xorg'' or
``XFree86''.
Default: ``Xorg'' on amd64, i386, macppc, shark and sparc64
platforms, ``XFree86'' on everything else.
"make" variables for full builds
These variables only affect the top level ``Makefile'' and do not affect
manually building subtrees of the NetBSD source code.
INSTALLWORLDDIR Location for the ``make installworld'' target to install
to. If specified, must be an absolute path.
Default: ``/''
MKOBJDIRS Can be set to ``yes'' or ``no''. Indicates whether
object directories will be created automatically (via a
``make obj'' pass) at the start of a build.
Default: ``no''
If using build.sh, the default is ``yes''. This may be
set back to ``no'' by giving build.sh the -o option.
MKUPDATE Can be set to ``yes'' or ``no''. If set, then in addi-
tion to the effects described for MKUPDATE=yes above,
this implies the effects of NOCLEANDIR (i.e., ``make
cleandir'' is avoided).
Default: ``no''
If using build.sh, this may be set by giving the -u
option.
NBUILDJOBS Now obsolete. Use the make(1) option -j, instead. See
below.
Default: Unset.
NOCLEANDIR If set, avoids the ``make cleandir'' phase of a full
build. This has the effect of allowing only changed
files in a source tree to be recompiled. This can speed
up builds when updating only a few files in the tree.
Default: Unset.
See also MKUPDATE.
NODISTRIBDIRS If set, avoids the ``make distrib-dirs'' phase of a full
build. This skips running mtree(8) on DESTDIR, useful
on systems where building as an unprivileged user, or
where it is known that the system-wide mtree files have
not changed.
Default: Unset.
NOINCLUDES If set, avoids the ``make includes'' phase of a full
build. This has the effect of preventing make(1) from
thinking that some programs are out-of-date simply
because the system include files have changed. However,
this option should not be used when updating the entire
NetBSD source tree arbitrarily; it is suggested to use
MKUPDATE=yes instead in that case.
Default: Unset.
RELEASEDIR If set, specifies the directory to which a release(7)
layout will be written at the end of a ``make release''.
If specified, must be an absolute path.
Default: Unset.
Note: build.sh will provide a default of releasedir (in
the top-level .OBJDIR) unless run in `expert' mode.
BUILDING
"make" command line options
This is not a summary of all the options available to make(1); only the
options used most frequently with NetBSD builds are listed here.
-j njob Run up to njob make(1) subjobs in parallel. Makefiles should
use .WAIT or have explicit dependencies as necessary to
enforce build ordering.
-m dir Specify the default directory for searching for system Make-
file segments, mainly the <bsd.*.mk> files. When building any
full NetBSD source tree, this should be set to the
``share/mk'' directory in the source tree. This is set auto-
matically when building from the top level, or when using
build.sh.
-n Display the commands that would have been executed, but do not
actually execute them. This will still cause recursion to
take place.
-V var Print make(1)'s idea of the value of var. Does not build any
targets.
var=value Set the variable var to value, overriding any setting speci-
fied by the process environment, the MAKECONF configuration
file, or the system Makefile segments.
"make" targets
These default targets may be built by running make(1) in any subtree of
the NetBSD source code. It is recommended that none of these be used
from the top level Makefile; as a specific exception, ``make obj'' and
``make cleandir'' are useful in that context.
all Build programs, libraries, and preformatted documentation.
clean Remove program and library object code files.
cleandir Same as clean, but also remove preformatted documentation,
dependency files generated by ``make depend'', and any other
files known to be created at build time.
depend Create dependency files (.depend) containing more detailed
information about the dependencies of source code on header
files. Allows programs to be recompiled automatically when a
dependency changes.
dependall Does a ``make depend'' immediately followed by a ``make all''.
This improves cache locality of the build since both passes
read the source files in their entirety.
distclean Synonym for cleandir.
includes Build and install system header files. Typically needed
before any system libraries or programs can be built.
install Install programs, libraries, and documentation into DESTDIR.
Few files will be installed to DESTDIR/dev, DESTDIR/etc,
DESTDIR/root or DESTDIR/var in order to prevent user supplied
configuration data from being overwritten.
lint Run lint(1) against the C source code, where appropriate, and
generate system-installed lint libraries.
obj Create object directories to be used for built files, instead
of building directly in the source tree.
tags Create ctags(1) searchable function lists usable by the ex(1)
and vi(1) text editors.
"make" targets for the top level
Additional make(1) targets are usable specifically from the top source
level to facilitate building the entire NetBSD source tree.
build Build the entire NetBSD system (except the kernel). This
orders portions of the source tree such that prerequisites
will be built in the proper order.
distribution Do a ``make build'', and then install a full distribution
(which does not include a kernel) into DESTDIR, including
files in DESTDIR/dev, DESTDIR/etc, DESTDIR/root and
DESTDIR/var.
buildworld As per ``make distribution'', except that it ensures that
DESTDIR is not the root directory.
installworld Install the distribution from DESTDIR to INSTALLWORLDDIR,
which defaults to the root directory. Ensures that
INSTALLWORLDDIR is not the root directory if cross compil-
ing.
The INSTALLSETS environment variable may be set to a space-
separated list of distribution sets to be installed. By
default, all sets except ``etc'' and ``xetc'' are
installed, so most files in INSTALLWORLDDIR/etc will not be
installed or modified.
Note: Before performing this operation with
INSTALLWORLDDIR=/, it is highly recommended that you
upgrade your kernel and reboot. After performing this
operation, it is recommended that you use etcupdate(8) to
update files in INSTALLWORLDDIR/etc, and postinstall(8) to
check for or fix inconsistencies.
sets Create distribution sets from DESTDIR into
RELEASEDIR/RELEASEMACHINEDIR/binary/sets. Should be run
after ``make distribution'', as ``make build'' alone does
not install all of the required files.
sourcesets Create source sets of the source tree into
RELEASEDIR/source/sets.
syspkgs Create syspkgs from DESTDIR into
RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs. Should be run
after ``make distribution'', as ``make build'' alone does
not install all of the required files.
release Do a ``make distribution'', build kernels, distribution
media, and install sets (this as per ``make sets''), and
then package the system into a standard release layout as
described by release(7). This requires that RELEASEDIR be
set (see above).
iso-image Create a NetBSD installation CD-ROM image in the
RELEASEDIR/iso directory. The CD-ROM file system will have
a layout as described in release(7).
For most machine types, the CD-ROM will be bootable, and
will automatically run the sysinst(8) menu-based installa-
tion program, which can be used to install or upgrade a
NetBSD system. Bootable CD-ROMs also contain tools that
may be useful in repairing a damaged NetBSD installation.
Before ``make iso-image'' is attempted, RELEASEDIR must be
populated by ``make release'' or equivalent.
Note that other, smaller, CD-ROM images may be created in
the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom direc-
tory by ``make release''. These smaller images usually
contain the same tools as the larger images in
RELEASEDIR/iso, but do not contain additional content such
as the distribution sets.
Note that the mac68k port still uses an older method of
creating CD-ROM images. This requires the mkisofs(1) util-
ity, which is not part of NetBSD, but which can be
installed from pkgsrc/sysutils/cdrtools.
iso-image-source
Create a NetBSD installation CD-ROM image in the
RELEASEDIR/iso directory. The CD-ROM file system will have
a layout as described in release(7). It will have top
level directories for the machine type and source.
For most machine types, the CD-ROM will be bootable, and
will automatically run the sysinst(8) menu-based installa-
tion program, which can be used to install or upgrade a
NetBSD system. Bootable CD-ROMs also contain tools that
may be useful in repairing a damaged NetBSD installation.
Before ``make iso-image-source'' is attempted, RELEASEDIR
must be populated by ``make sourcesets release'' or equiva-
lent.
Note that other, smaller, CD-ROM images may be created in
the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom direc-
tory by ``make release''. These smaller images usually
contain the same tools as the larger images in
RELEASEDIR/iso, but do not contain additional content such
as the distribution sets.
Note that the mac68k port still uses an older method of
creating CD-ROM images. This requires the mkisofs(1) util-
ity, which is not part of NetBSD, but which can be
installed from pkgsrc/sysutils/cdrtools.
install-image
Create a bootable NetBSD installation disk image in the
RELEASEDIR/RELEASEMACHINEDIR/installation/installimage
directory. The installation disk image is suitable for
copying to bootable USB flash memory sticks, etc., for
machines which are able to boot from such devices. The
file system in the bootable disk image will have a layout
as described in release(7).
The installation image is bootable, and will automatically
run the sysinst(8) menu-based installation program, which
can be used to install or upgrade a NetBSD system. The
image also contains tools that may be useful in repairing a
damaged NetBSD installation.
Before ``make install-image'' is attempted, RELEASEDIR must
be populated by ``make release'' or equivalent. The build
must have been performed with MKUNPRIVED=yes because ``make
install-image'' relies on information in DESTDIR/METALOG.
live-image Create NetBSD live images in the
RELEASEDIR/RELEASEMACHINEDIR/installation/liveimage direc-
tory. The live image contains all necessary files to boot
NetBSD up to multi-user mode, including all files which
should be extracted during installation, NetBSD disklabel,
bootloaders, etc.
The live image is suitable for use as a disk image in vir-
tual machine environments such as QEMU, and also useful to
boot NetBSD from a USB flash memory stick on a real
machine, without the need for installation.
Before ``make live-image'' is attempted, RELEASEDIR must be
populated by ``make release'' or equivalent. The build
must have been performed with MKUNPRIVED=yes because ``make
install-image'' relies on information in DESTDIR/METALOG.
regression-tests
Can only be run after building the regression tests in the
directory ``regress''. Runs those compiled regression
tests on the local host. Note that most tests are now man-
aged instead using atf(7); this target should probably run
those as well but currently does not.
The "build.sh" script
This script file is a shell script designed to build the entire NetBSD
system on any host with a suitable modern shell and some common utili-
ties. The required shell features are described under the HOST_SH vari-
able.
If a host system's default shell does support the required features, then
we suggest that you explicitly specify a suitable shell using a command
like
/path/to/suitable/shell build.sh [options]
The above command will usually enable build.sh to automatically set
HOST_SH=/path/to/suitable/shell, but if that fails, then the following
set of commands may be used instead:
HOST_SH=/path/to/suitable/shell
export HOST_SH
${HOST_SH} build.sh [options]
If build.sh detects that it is being executed under an unsuitable shell,
it attempts to exec a suitable shell instead, or prints an error message.
If HOST_SH is not set explicitly, then build.sh sets a default using
heuristics dependent on the host platform, or from the shell under which
build.sh is executed (if that can be determined), or using the first copy
of sh found in PATH.
All cross-compile builds, and most native builds, of the entire system
should make use of build.sh rather than just running ``make''. This way,
the make(1) program will be bootstrapped properly, in case the host sys-
tem has an older or incompatible ``make'' program.
When compiling the entire system via build.sh, many make(1) variables are
set for you in order to help encapsulate the build process. In the list
of options below, variables that are automatically set by build.sh are
noted where applicable.
The following operations are supported by build.sh:
build Build the system as per ``make build''. Before the main
part of the build commences, this command runs the obj
operation (unless the -o option is given), ``make
cleandir'' (unless the -u option is given), and the tools
operation.
distribution Build a full distribution as per ``make distribution''.
This command first runs the build operation.
release Build a full release as per ``make release''. This command
first runs the distribution operation.
makewrapper Create the nbmake-MACHINE wrapper. This operation is auto-
matically performed for any of the other operations.
cleandir Perform ``make cleandir''.
obj Perform ``make obj''.
tools Build and install the host tools from src/tools. This com-
mand will first run ``make obj'' and ``make cleandir'' in
the tools subdirectory unless the -o or -u options (respec-
tively) are given.
install=idir Install the contents of DESTDIR to idir, using ``make
installworld''. Note that files that are part of the
``etc'' or ``xetc'' sets will not be installed, unless
overridden by the INSTALLSETS environment variable.
kernel=kconf Build a new kernel. The kconf argument is the name of a
configuration file suitable for use by config(1). If kconf
does not contain any `/' characters, the configuration file
is expected to be found in the KERNCONFDIR directory, which
is typically sys/arch/MACHINE/conf. The new kernel will be
built in a subdirectory of KERNOBJDIR, which is typically
sys/arch/MACHINE/compile or an associated object directory.
This command does not imply the tools command; run the
tools command first unless it is certain that the tools
already exist and are up to date.
This command will run ``make cleandir'' on the kernel in
question first unless the -u option is given.
modules This command will build kernel modules and install them
into DESTDIR.
releasekernel=kconf
Install a gzip(1)ed copy of the kernel previously built by
kernel=kconf into
RELEASEDIR/RELEASEMACHINEDIR/binary/kernel, usually as
netbsd-kconf.gz, although the ``netbsd'' prefix is deter-
mined from the ``config'' directives in kconf.
sets Perform ``make sets''.
sourcesets Perform ``make sourcesets''.
syspkgs Perform ``make syspkgs''.
iso-image Perform ``make iso-image''.
iso-image-source
Perform ``make iso-image-source''.
install-image
Perform ``make install-image''.
live-image Perform ``make live-image''.
The following command line options alter the behaviour of the build.sh
operations described above:
-a arch Set the value of MACHINE_ARCH to arch.
-B buildid
Set the value of BUILDID to buildid. This will also append the
build identifier to the name of the ``make'' wrapper script so
that the resulting name is of the form
``nbmake-MACHINE-BUILDID''.
-C cdextras
Append cdextras to the CDEXTRA variable, which is a space-sepa-
rated list of files or directories that will be added to the
CD-ROM image that may be create by the ``iso-image'' or
``iso-image-source'' operations. Files will be added to the
root of the CD-ROM image, whereas directories will be copied
recursively. If relative paths are specified, they will be
converted to absolute paths before being used. Multiple paths
may be specified via multiple -C options, or via a single
option whose argument contains multiple space-separated paths.
-D dest Set the value of DESTDIR to dest. If a relative path is speci-
fied, it will be converted to an absolute path before being
used.
-E Set `expert' mode. This overrides various sanity checks, and
allows: DESTDIR does not have to be set to a non-root path for
builds, and MKUNPRIVED=yes does not have to be set when build-
ing as a non-root user.
Note: It is highly recommended that you know what you are doing
when you use this option.
-h Print a help message.
-j njob Run up to njob make(1) subjobs in parallel; passed through to
make(1). If you see failures for reasons other than running
out of memory while using build.sh with -j, please save com-
plete build logs so the failures can be analyzed.
To achieve the fastest builds, -j values between (1 + the num-
ber of CPUs) and (2 * the number of CPUs) are recommended. Use
lower values on machines with limited memory or I/O bandwidth.
-M obj Set MAKEOBJDIRPREFIX to obj. Unsets MAKEOBJDIR. See ``-O
-obj'' for more information.
For instance, if the source directory is /usr/src, a setting of
``-M /usr/obj'' will place build-time files under
/usr/obj/usr/src/bin, /usr/obj/usr/src/lib,
/usr/obj/usr/src/usr.bin, and so forth.
If a relative path is specified, it will be converted to an
absolute path before being used. build.sh imposes the restric-
tion that the argument to the -M option must not begin with a
``$'' (dollar sign) character; otherwise it would be too diffi-
cult to determine whether the value is an absolute or a rela-
tive path. If the directory does not already exist, build.sh
will create it.
-m mach Set the value of MACHINE to mach, except in some special cases
listed below. This will also override any value of
MACHINE_ARCH in the process environment with a value deduced
from mach, unless -a is specified. All cross builds require
-m, but if unset on a NetBSD host, the host's value of MACHINE
will be detected and used automatically.
Some machines support multiple values for MACHINE_ARCH. The
following special cases for the mach argument are defined to
set the listed values of MACHINE and MACHINE_ARCH:
mach MACHINE MACHINE_ARCH
evbarm evbarm (not set)
evbarm-eb evbarm armeb
evbarm-el evbarm arm
evbmips evbmips (not set)
evbmips-eb evbmips mipseb
evbmips-el evbmips mipsel
evbsh3 evbsh3 (not set)
evbsh3-eb evbsh3 sh3eb
evbsh3-el evbsh3 sh3el
sbmips sbmips (not set)
sbmips-eb sbmips mipseb
sbmips-el sbmips mipsel
-N noiselevel
Set the ``noisyness'' level of the build, by setting
MAKEVERBOSE to noiselevel.
-n Show the commands that would be executed by build.sh, but do
not make any changes. This is similar in concept to ``make
-n''.
-O obj Create an appropriate transform macro for MAKEOBJDIR that will
place the built object files under obj. Unsets
MAKEOBJDIRPREFIX.
For instance, a setting of ``-O /usr/obj'' will place build-
time files under /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin,
and so forth.
If a relative path is specified, it will be converted to an
absolute path before being used. build.sh imposes the restric-
tion that the argument to the -O option must not contain a
``$'' (dollar sign) character. If the directory does not
already exist, build.sh will create it.
In normal use, exactly one of the -M or -O options should be
specified. If neither -M nor -O is specified, then a default
object directory will be chosen according to rules in
<bsd.obj.mk>. Relying on this default is not recommended
because it is determined by complex rules that are influenced
by the values of several variables and by the location of the
source directory.
-o Set the value of MKOBJDIRS to ``no''. Otherwise, it will be
automatically set to ``yes''. This default is opposite to the
behaviour when not using build.sh.
-R rel Set the value of RELEASEDIR to rel. If a relative path is
specified, it will be converted to an absolute path before
being used.
-r Remove the contents of DESTDIR and TOOLDIR before building
(provides a clean starting point). This will skip deleting
DESTDIR if building on a native system to the root directory.
-S seed Change the value of BUILDSEED to seed. This should rarely be
necessary.
-T tools Set the value of TOOLDIR to tools. If a relative path is spec-
ified, it will be converted to an absolute path before being
used. If set, the bootstrap ``make'' will only be rebuilt if
the source files for make(1) have changed.
-U Set MKUNPRIVED=yes.
-u Set MKUPDATE=yes.
-V var=[value]
Set the environment variable var to an optional value. This is
propagated to the nbmake wrapper.
-w wrapper
Create the nbmake wrapper script (see below) in a custom loca-
tion, specified by wrapper. This allows, for instance, to
place the wrapper in PATH automatically. Note that wrapper is
the full name of the file, not just a directory name. If a
relative path is specified, it will be converted to an absolute
path before being used.
-X x11src
Set the value of X11SRCDIR to x11src. If a relative path is
specified, it will be converted to an absolute path before
being used.
-x Set MKX11=yes.
-Z var Unset ("zap") the environment variable var. This is propagated
to the nbmake wrapper.
The "nbmake-MACHINE" wrapper script
If using the build.sh script to build NetBSD, a nbmake-MACHINE script
will be created in TOOLDIR/bin upon the first build to assist in building
subtrees on a cross-compile host.
nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev-
eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR.
nbmake-MACHINE will also set variables specified with -V, and unset vari-
ables specified with -Z.
This script can be symlinked into a directory listed in PATH, or called
with an absolute path.
EXAMPLES
1. % ./build.sh [options] tools kernel=GENERIC
Build a new toolchain, and use the new toolchain to configure and
build a new GENERIC kernel.
2. % ./build.sh [options] -U distribution
Using unprivileged mode, build a complete distribution to a DESTDIR
directory that build.sh selects (and will display).
3. # ./build.sh [options] -U install=/
As root, install to / the distribution that was built by example 2.
Even though this is run as root, -U is required so that the permis-
sions stored in DESTDIR/METALOG are correctly applied to the files
as they're copied to /.
4. % ./build.sh [options] -U -u release
Using unprivileged mode, build a complete release to DESTDIR and
RELEASEDIR directories that build.sh selects (and will display).
MKUPDATE=yes (-u) is set to prevent the ``make cleandir'', so that
if this is run after example 2, it doesn't need to redo that portion
of the release build.
OBSOLETE VARIABLES
NBUILDJOBS Use the make(1) option -j instead.
USE_NEW_TOOLCHAIN
The new toolchain is now the default. To disable, use
TOOLCHAIN_MISSING=yes.
SEE ALSO
make(1), hier(7), release(7), etcupdate(8), postinstall(8), sysinst(8),
pkgsrc/sysutils/cdrtools