Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files. =================================================================== RCS file: /ftp/cvs/cvsroot/src/BUILDING,v rcsdiff: /ftp/cvs/cvsroot/src/BUILDING,v: warning: Unknown phrases like `commitid ...;' are present. retrieving revision 1.105 retrieving revision 1.116 diff -u -p -r1.105 -r1.116 --- src/BUILDING 2013/05/29 21:59:51 1.105 +++ src/BUILDING 2014/11/16 05:45:43 1.116 @@ -49,6 +49,12 @@ FILES ``reachover'' Makefile semantics when building these programs for a native host. + external, sys/external + Sources and build infrastructure for components imported + (mostly) unchanged from upstream maintainers, sorted by + applicable license. This is (slowly) replacing the + crypto/dist, dist, and gnu/dist directories. + distrib/, etc/ Sources for items used when making a full release snapshot, such as files installed in DESTDIR/etc on the @@ -74,6 +80,9 @@ FILES x11/ ``Reachover'' build structure for X11R6; the source is in X11SRCDIR. + extsrc/ ``Reachover'' build structure for externally added + programs and libraries; the source is in EXTSRCSRCDIR. + Build tree layout The NetBSD build tree is described in hier(7), and the release layout is described in release(7). @@ -145,10 +154,27 @@ CONFIGURATION otherwise specified, these variables may be set in either the process environment 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) + BUILDID Identifier for the build. If set, this should be a short + string that is suitable for use as part of a file or + directory name. 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 - parameters, such as compiler flags. + parameters, such as compiler flags. It will also be used as + part of the kernel version string, which can be printed by + ``uname -v''. + + Default: Unset. + + BUILDINFO This may be a multi-line string containing information about + the build. This will appear in DESTDIR/etc/release, and it + will be stored in the buildinfo variable in any kernels that + are built. When such kernels are booted, the sysctl(7) + kern.buildinfo variable will report this value. The string + may contain backslash escape sequences, such as ``\\'' + (representing a backslash character) and ``\n'' (representing + a newline). + + Default: Unset. BUILDSEED GCC uses random numbers when compiling C++ code. This variable seeds the gcc random number generator using the @@ -174,6 +200,13 @@ CONFIGURATION Note: build.sh will provide a default of destdir.MACHINE (in the top-level .OBJDIR) unless run in `expert' mode. + EXTSRCSRCDIR + Directory containing sources of externally added programs and + libraries. If specified, must be an absolute path. + + Default: NETBSDRCDIR/../extsrc, if that exists; otherwise + /usr/extsrc. + MAKECONF The name of the make(1) configuration file. Only settable in the process environment. @@ -209,6 +242,11 @@ CONFIGURATION Default: ``no'' + MKCROSSGDB Can be set to ``yes'' or ``no''. Create a cross-gdb as a + host tool. + + Default: ``no'' + MKCRYPTO Can be set to ``yes'' or ``no''. Indicates whether cryptographic code will be included in a build; provided for the benefit of countries that do not allow strong @@ -217,12 +255,30 @@ CONFIGURATION Default: ``yes'' + MKDEBUG Can be set to ``yes'' or ``no''. Indicates whether debug + information should be generated for all userland binaries + compiled. The result is collected as an additional debug.tgz + and xdebug.tgz set and installed in /usr/libdata/debug. + + Default: ``no'' + + MKDEBUGLIB Can be set to ``yes'' or ``no''. Indicates whether debug + information (see MKDEBUG) should also be generated for all + libraries build. + + Default: ``no'' + 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'' + MKEXTSRC Can be set to ``yes'' or ``no''. Indicates whether extsrc is + built from EXTSRCSRCDIR. + + Default: ``no'' + MKHTML Can be set to ``yes'' or ``no''. Indicates whether preformatted HTML manual pages will be built and installed @@ -245,6 +301,14 @@ CONFIGURATION Default: ``yes'' + MKKDEBUG Can be set to ``yes'' or ``no''. Force generation of full- + debug symbol versions of all kernels compiled. Alongside of + the netbsd kernel file, an unstripped version netbsd.gdb is + created. This is useful if a cross-gdb is built as well (see + MKCROSSGDB). + + Default: ``no'' + MKKMOD Can be set to ``yes'' or ``no''. Indicates whether kernel modules are built and installed. @@ -583,8 +647,8 @@ BUILDING 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). + RELEASEDIR/images 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 @@ -600,8 +664,8 @@ BUILDING the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom directory 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. + RELEASEDIR/images, 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) @@ -610,8 +674,8 @@ BUILDING 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 + RELEASEDIR/images 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 @@ -629,8 +693,8 @@ BUILDING the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom directory 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. + RELEASEDIR/images, 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) @@ -764,6 +828,24 @@ BUILDING This command will run ``make cleandir'' on the kernel in question first unless the -u option is given. + kernel.gdb=kconf + Build a new kernel with debug information. Similar to the + above kernel=kconf operation, but creates a netbsd.gdb file + alongside of the kernel netbsd, which contains a full + symbol table and can be used for debugging (for example + with a cross-gdb built by MKCROSSGDB). + + mkernel=kconf + Build a new kernel in modular build. Similar to the above + kernel=kconf operation, but creates intermediate per-module + relocatable objects and link them to the final kernel. + + kernels This command will build all kernels defined in port + specific release build procedure. + + This command internally calls the kernel=kconf operation + for each found kernel configuration file. + modules This command will build kernel modules and install them into DESTDIR. @@ -790,10 +872,21 @@ BUILDING live-image Perform ``make live-image''. + list-arch Prints a list of valid MACHINE and MACHINE_ARCH settings, + the default MACHINE_ARCH for each MACHINE, and aliases for + MACHINE/MACHINE_ARCH pairs, and then exits. The -m or -a + options (or both) may be used to specify glob patterns that + will be used to narrow the list of results; for example, + ``build.sh -m 'evm*' -a '*arm*' list-arch'' will list all + known MACHINE/MACHINE_ARCH values in which either MACHINE + or ALIAS matches the pattern `evb*', and MACHINE_ARCH + matches the pattern `*arm*'. + 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. + -a arch Set the value of MACHINE_ARCH to arch. See the -m option for + more information. -B buildid Set the value of BUILDID to buildid. This will also append the @@ -837,7 +930,7 @@ BUILDING bandwidth. -M obj Set MAKEOBJDIRPREFIX to obj. Unsets MAKEOBJDIR. See ``-O - -obj'' for more information. + 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 @@ -852,30 +945,19 @@ BUILDING relative 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 + -m mach Set the value of MACHINE to mach, unless the mach argument is + an alias that refers to a MACHINE/MACHINE_ARCH pair, in which + case both MACHINE and MACHINE_ARCH are set from the alias. + Such aliases are interpreted entirely by build.sh; they are not + used by any other part of the build system. The MACHINE_ARCH + setting implied by mach will override any value of MACHINE_ARCH + in the process environment, but will not override a value set + by the -a option. All cross builds require -m, but if unset on + a NetBSD host, the host's value of MACHINE will be detected and + used automatically. + + See the list-arch operation for a way to get a list of valid + MACHINE and MACHINE_ARCH settings. -N noiselevel Set the ``noisyness'' level of the build, by setting @@ -907,6 +989,16 @@ BUILDING by the values of several variables and by the location of the source directory. + Note that placing the obj directory location outside of the + default source tree hierarchy makes it easier to manually clear + out old files in the event the ``make cleandir'' operation is + unable to do so. (See CAVEATS below.) + + Note also that use of one of -M or -O is the only means of + building multiple machine architecture userlands from the same + source tree without cleaning between builds (in which case, one + would specify distinct obj locations for each). + -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. @@ -950,6 +1042,13 @@ BUILDING -x Set MKX11=yes. + -Y extsrcdir + Set the value of EXTSRCSRCDIR to extsrcdir. If a relative path + is specified, it will be converted to an absolute path before + being used. + + -y Set MKEXTSRC=yes. + -Z var Unset ("zap") the environment variable var. This is propagated to the nbmake wrapper. @@ -1008,4 +1107,10 @@ HISTORY The build.sh based build scheme was introduced for NetBSD 1.6 as USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that. -NetBSD November 8, 2012 NetBSD +CAVEATS + After significant updates to third-party components in the source tree, + the ``make cleandir'' operation may be insufficient to clean out old + files in object directories. Instead, one may have to manually remove + the files. Consult the UPDATING file for notices concerning this. + +NetBSD August 7, 2014 NetBSD