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 April 12, 2009
  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 Refer to
  46 .Xr development 7
  47 for more information on how to obtain the
  48 .Dx
  49 sources.
  50 .Pp
  51 Third party applications have to be built using the
  52 .Xr pkgsrc 7
  53 system.
  54 The file
  55 .Pa /usr/src/UPDATING
  56 gives specifics on how to obtain the tree for building packages.
  57 .Pp
  58 The
  59 .Xr make 1
  60 command is used in
  61 .Pa /usr/src
  62 to build and install the things in that directory.
  63 Issuing the
  64 .Xr make 1
  65 command in any directory or
  66 subdirectory of those directories has the same effect as issuing the
  67 same command in all subdirectories of that directory.
  68 With no target specified, the things in that directory are just built.
  69 The following list provides the names and actions for other targets:
  70 .Bl -tag -width ".Cm install"
  71 .It Cm clean
  72 Removes any files created during the build process.
  73 .It Cm install
  74 Installs the results of the build for this directory.
  75 .El
  76 .Pp
  77 The other
  78 .Pa /usr/src
  79 make targets are:
  80 .Bl -tag -width ".Cm reinstallkernel"
  81 .It Cm buildworld
  82 Rebuild everything but the kernel.
  83 .It Cm quickworld
  84 Same as
  85 .Cm buildworld ,
  86 but skip bootstrap, build and cross-build tool steps.
  87 This target can be used for incremental upgrades once a full build of the
  88 world has been done with
  89 .Cm buildworld .
  90 .It Cm realquickworld
  91 Same as
  92 .Cm quickworld ,
  93 but also skip the depend step.
  94 .It Cm crossworld
  95 Just do the bootstrap, build and cross-build steps.
  96 .It Cm installworld
  97 Install everything built by
  98 .Cm buildworld .
  99 .It Cm world
 100 .Cm buildworld +
 101 .Cm installworld .
 102 .It Cm buildkernel
 103 Rebuild the kernel and the kernel-modules.
 104 .It Cm nativekernel
 105 Rebuild the kernel and the kernel-modules using native tools.
 106 .It Cm quickkernel
 107 Same as
 108 .Cm buildkernel ,
 109 but skip the depend step and do not clean out the
 110 obj modules.
 111 This target can be used for incremental upgrades once a full
 112 build of the kernel has been done with
 113 .Cm buildkernel .
 114 .It Cm installkernel
 115 Install the kernel and the kernel-modules.
 116 .It Cm reinstallkernel
 117 Reinstall the kernel and the kernel-modules.
 118 .It Cm kernel
 119 .Cm buildkernel +
 120 .Cm installkernel .
 121 .It Cm preupgrade
 122 Perform certain upgrades that have to be done before
 123 .Cm installworld .
 124 .Cm installworld
 125 will complain if they have not been done.
 126 .It Cm upgrade
 127 Upgrade the files in /etc and also setup the rest of the system for
 128 the version of
 129 .Dx
 130 just installed.
 131 .It Cm most
 132 Build user commands, no libraries or include files.
 133 .It Cm installmost
 134 Install user commands, no libraries or include files.
 135 .El
 136 .Sh ENVIRONMENT
 137 .Bl -tag -width ".Ev MAKEOBJDIRPREFIX"
 138 .It Ev TARGET_ARCH , TARGET_PLATFORM
 139 The target machine processor architecture and hardware platform.
 140 These have to be set for cross-building.
 141 .Ev TARGET_ARCH
 142 is analogous to the
 143 .Dq Nm uname Fl p
 144 output.
 145 To build for the 32 bit
 146 .Tn Intel
 147 architecture known as IA-32, x86 or x86-32, use:
 148 .Bd -literal -offset indent
 149 TARGET_ARCH=i386
 150 TARGET_PLATFORM=pc32
 151 .Ed
 152 .Pp
 153 For the 64 bit
 154 .Tn AMD
 155 architecture known as AMD64, x86-64 or Intel 64, use:
 156 .Bd -literal -offset indent
 157 TARGET_ARCH=x86_64
 158 TARGET_PLATFORM=pc64
 159 .Ed
 160 .It Ev DESTDIR
 161 An existing directory to be the root of
 162 the hierarchy where the resulting binaries will be
 163 installed (the default is
 164 .Pa / ) .
 165 .It Ev MAKEOBJDIRPREFIX
 166 The directory hierarchy where the object files will be built (the default is
 167 .Pa /usr/obj ) .
 168 .It Ev __MAKE_CONF
 169 Used to override the path of
 170 .Xr make.conf 5
 171 (the default is
 172 .Pa /etc/make.conf ) .
 173 .It Ev KERNCONF
 174 The name of the kernel configuration file from which the kernel should
 175 be built (the default is
 176 .Li GENERIC ) .
 177 .It Ev KERNCONFDIR
 178 The directory where the kernel configuration files are kept (the default is
 179 .Pa /usr/src/sys/config ) .
 180 .It Ev DESTLABEL
 181 Common suffix added to kernel and modules directory names, prefixed by
 182 a single dot.  For example,
 183 .Bd -literal -offset indent
 184 make DESTLABEL=test installkernel
 185 .Ed
 186 .Pp
 187 installs them as
 188 .Pa /boot/kernel.test
 189 and
 190 .Pa /boot/modules.test ,
 191 respectively.
 192 .It Ev DESTKERNDIR
 193 Where to install the kernel and the modules (the default is
 194 .Pa /boot ) ,
 195 in the directory hierarchy specified by the environment variable
 196 .Ev DESTDIR .
 197 .It Ev DESTKERNNAME
 198 The name of the installed kernel file (the default is
 199 .Pa kernel ) ,
 200 under the directory specified by
 201 .Ev DESTKERNDIR .
 202 This overrides the effect of
 203 .Ev DESTLABEL .
 204 .It Ev DESTMODULESNAME
 205 The name of the directory to install the kernel modules (the default is
 206 .Pa modules ) ,
 207 under the directory specified by
 208 .Ev DESTKERNDIR .
 209 This overrides the effect of
 210 .Ev DESTLABEL .
 211 .El
 212 .Sh FILES
 213 .Bl -tag -width ".Pa /usr/src/Makefile_upgrade.inc" -compact
 214 .It Pa /etc/make.conf
 215 .It Pa /etc/defaults/make.conf
 216 .It Pa /usr/src/share/doc/Makefile
 217 .It Pa /usr/src/Makefile
 218 .It Pa /usr/src/Makefile.inc1
 219 .It Pa /usr/src/Makefile_upgrade.inc
 220 .El
 221 .Sh EXAMPLES
 222 The
 223 .Dq approved
 224 method of updating your system from the latest sources is:
 225 .Bd -literal -offset indent
 226 make buildworld
 227 make buildkernel KERNCONF=FOO
 228 make installkernel KERNCONF=FOO
 229 make installworld
 230 make upgrade
 231 .Ed
 232 .Pp
 233 After running these commands a system reboot is required,
 234 otherwise many programs which have been rebuilt (such as
 235 .Xr ps 1 ,
 236 .Xr top 1 ,
 237 etc.) may not work with the old kernel which is still running.
 238 .Sh CAVEATS
 239 The build and install order in the
 240 .Sx EXAMPLES
 241 section enforces that the new kernel is installed before the new
 242 world.
 243 Sometimes it might be necessary to reboot the system between those two
 244 steps.
 245 In this case
 246 .Dq Nm make Cm installworld
 247 will tell you to do so.
 248 .Sh SEE ALSO
 249 .Xr cc 1 ,
 250 .Xr install 1 ,
 251 .Xr make 1 ,
 252 .Xr wmake 1 ,
 253 .Xr make.conf 5 ,
 254 .Xr development 7 ,
 255 .Xr pkgsrc 7 ,
 256 .Xr release 7 ,
 257 .Xr config 8 ,
 258 .Xr reboot 8 ,
 259 .Xr shutdown 8
 260 .Sh AUTHORS
 261 .An -nosplit
 262 .An Mike W. Meyer Aq mwm@mired.org
 263 and
 264 .An Sascha Wildner Aq swildner@gmail.com .