share/man/man7/build.7

   1 .\" Copyright (c) 2000
   2 .\"     Mike W. Meyer
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  12 .\"
  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
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/share/man/man7/build.7,v 1.19.2.1 2002/03/18 08:33:02 murray Exp $
  26 .\" $DragonFly: src/share/man/man7/build.7,v 1.18 2008/11/14 15:04:42 swildner Exp $
  27 .\"
  28 .Dd December 1, 2008
  29 .Dt BUILD 7
  30 .Os
  31 .Sh NAME
  32 .Nm build
  33 .Nd information on how to build the system
  34 .Sh DESCRIPTION
  35 The source for the
  36 .Dx
  37 system and applications is located in
  38 .Pa /usr/src .
  39 This directory contains the
  40 .Dq "base system"
  41 sources, which is loosely defined as the things required to rebuild
  42 the system to a useful state.
  43 It also contains the source for the system documentation, including
  44 manual pages.
  45 Third party applications have to be built using the
  46 .Xr pkgsrc 7
  47 system.
  48 The file
  49 .Pa /usr/src/UPDATING
  50 gives specifics on how to obtain the tree for building packages.
  51 .Pp
  52 The
  53 .Xr make 1
  54 command is used in
  55 .Pa /usr/src
  56 to build and install the things in that directory.
  57 Issuing the
  58 .Xr make 1
  59 command in any directory or
  60 subdirectory of those directories has the same effect as issuing the
  61 same command in all subdirectories of that directory.
  62 With no target specified, the things in that directory are just built.
  63 The following list provides the names and actions for other targets:
  64 .Bl -tag -width ".Cm install"
  65 .It Cm clean
  66 Removes any files created during the build process.
  67 .It Cm install
  68 Installs the results of the build for this directory.
  69 .El
  70 .Pp
  71 The other
  72 .Pa /usr/src
  73 make targets are:
  74 .Bl -tag -width ".Cm reinstallkernel"
  75 .It Cm buildworld
  76 Rebuild everything but the kernel.
  77 .It Cm quickworld
  78 Same as
  79 .Cm buildworld ,
  80 but skip bootstrap, build and cross-build tool steps.
  81 This target can be used for incremental upgrades once a full build of the
  82 world has been done with
  83 .Cm buildworld .
  84 .It Cm realquickworld
  85 Same as
  86 .Cm quickworld ,
  87 but also skip the depend step.
  88 .It Cm crossworld
  89 Just do the bootstrap, build and cross-build steps.
  90 .It Cm installworld
  91 Install everything built by
  92 .Cm buildworld .
  93 .It Cm world
  94 .Cm buildworld +
  95 .Cm installworld .
  96 .It Cm buildkernel
  97 Rebuild the kernel and the kernel-modules.
  98 .It Cm nativekernel
  99 Rebuild the kernel and the kernel-modules using native tools.
 100 .It Cm quickkernel
 101 Same as
 102 .Cm buildkernel ,
 103 but skip the depend step and do not clean out the
 104 obj modules.
 105 This target can be used for incremental upgrades once a full
 106 build of the kernel has been done with
 107 .Cm buildkernel .
 108 .It Cm installkernel
 109 Install the kernel and the kernel-modules.
 110 .It Cm reinstallkernel
 111 Reinstall the kernel and the kernel-modules.
 112 .It Cm kernel
 113 .Cm buildkernel +
 114 .Cm installkernel .
 115 .It Cm preupgrade
 116 Perform certain upgrades that have to be done before
 117 .Cm installworld .
 118 .Cm installworld
 119 will complain if they have not been done.
 120 .It Cm upgrade
 121 Upgrade the files in /etc and also setup the rest of the system for
 122 the version of
 123 .Dx
 124 just installed.
 125 .It Cm most
 126 Build user commands, no libraries or include files.
 127 .It Cm installmost
 128 Install user commands, no libraries or include files.
 129 .El
 130 .Sh ENVIRONMENT
 131 .Bl -tag -width ".Ev TARGET_ARCH"
 132 .It Ev TARGET_ARCH
 133 The target machine processor architecture.
 134 This is analogous to the
 135 .Dq Nm uname Fl p
 136 output.
 137 .\"Set this to cross-build for a different architecture.
 138 .It Ev TARGET
 139 The target hardware platform.
 140 This is analogous to the
 141 .Dq Nm uname Fl m
 142 output.
 143 .\"This is necessary to cross-build some target architectures.
 144 .\".It Ev NO_WERROR
 145 .\"If defined, warnings will not cause the build to halt, even if the
 146 .\"makefile says otherwise.
 147 .It Ev DESTDIR
 148 An existing directory to be the root of
 149 the hierarchy where the resulting binaries will be
 150 installed (the default is
 151 .Pa / ) .
 152 .It Ev MAKEOBJDIRPREFIX
 153 The directory hierarchy where the object files will be built (the default is
 154 .Pa /usr/obj ) .
 155 .It Ev __MAKE_CONF
 156 Used to override the path of
 157 .Xr make.conf 5
 158 (the default is
 159 .Pa /etc/make.conf ) .
 160 .It Ev KERNCONF
 161 The name of the kernel configuration file from which the kernel should
 162 be built (the default is
 163 .Li GENERIC ) .
 164 .It Ev KERNCONFDIR
 165 The directory where the kernel configuration files are kept (the default is
 166 .Pa /usr/src/sys/config ) .
 167 .El
 168 .Sh FILES
 169 .Bl -tag -width ".Pa /usr/src/share/doc/Makefile" -compact
 170 .It Pa /etc/make.conf
 171 .It Pa /etc/defaults/make.conf
 172 .It Pa /usr/src/share/doc/Makefile
 173 .It Pa /usr/src/Makefile
 174 .It Pa /usr/src/Makefile.inc1
 175 .El
 176 .Sh EXAMPLES
 177 The
 178 .Dq approved
 179 method of updating your system from the latest sources is:
 180 .Bd -literal -offset indent
 181 make buildworld
 182 make buildkernel KERNCONF=FOO
 183 make installkernel KERNCONF=FOO
 184 make installworld
 185 make upgrade
 186 .Ed
 187 .Pp
 188 After running these commands a system reboot is required,
 189 otherwise many programs which have been rebuilt (such as
 190 .Xr ps 1 ,
 191 .Xr top 1 ,
 192 etc.) may not work with the old kernel which is still running.
 193 .Sh CAVEATS
 194 The build and install order in the
 195 .Sx EXAMPLES
 196 section enforces that the new kernel is installed before the new
 197 world.
 198 Sometimes it might be necessary to reboot the system between those two
 199 steps.
 200 In this case
 201 .Dq Nm make Cm installworld
 202 will tell you to do so.
 203 .Sh SEE ALSO
 204 .Xr cc 1 ,
 205 .Xr install 1 ,
 206 .Xr make 1 ,
 207 .Xr wmake 1 ,
 208 .Xr make.conf 5 ,
 209 .Xr development 7 ,
 210 .Xr pkgsrc 7 ,
 211 .Xr release 7 ,
 212 .Xr config 8 ,
 213 .Xr reboot 8 ,
 214 .Xr shutdown 8
 215 .Sh AUTHORS
 216 .An -nosplit
 217 .An Mike W. Meyer Aq mwm@mired.org
 218 and
 219 .An Sascha Wildner Aq swildner@gmail.com .