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.11 2006/05/17 14:41:48 swildner Exp $
  27 .\"
  28 .Dd May 17, 2006
  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 .Em pkgsrc
  47 system.
  48 The file
  49 .Pa /usr/src/UPDATING
  50 gives specifics on how to obtain the tree for building packages while
  51 .Xr packages 7
  52 describes the variables and targets that are available.
  53 .Pp
  54 The
  55 .Xr make 1
  56 command is used in
  57 .Pa /usr/src
  58 to build and install the things in that directory.
  59 Issuing the
  60 .Xr make 1
  61 command in any directory or
  62 subdirectory of those directories has the same effect as issuing the
  63 same command in all subdirectories of that directory.
  64 With no target specified, the things in that directory are just built.
  65 The following list provides the names and actions for other targets:
  66 .Bl -tag -width ".Cm install"
  67 .It Cm clean
  68 Removes any files created during the build process.
  69 .It Cm install
  70 Installs the results of the build for this directory.
  71 .It Cm update
  72 Gets updated sources as configured in
  73 .Pa /etc/make.conf .
  74 .El
  75 .Pp
  76 The other
  77 .Pa /usr/src
  78 make targets are:
  79 .Bl -tag -width ".Cm reinstallkernel"
  80 .It Cm buildworld
  81 Rebuild everything but the kernel.
  82 .It Cm quickworld
  83 Same as
  84 .Cm buildworld ,
  85 but skip bootstrap, build and cross-build tool steps.
  86 This target can be used for incremental upgrades once a full build of the
  87 world has been done with
  88 .Cm buildworld .
  89 .It Cm realquickworld
  90 Same as
  91 .Cm quickworld ,
  92 but also skip the depend step.
  93 .It Cm crossworld
  94 Just do the bootstrap, build and cross-build steps.
  95 .It Cm installworld
  96 Install everything built by
  97 .Cm buildworld .
  98 .It Cm world
  99 .Cm buildworld +
 100 .Cm installworld .
 101 .It Cm buildkernel
 102 Rebuild the kernel and the kernel-modules.
 103 .It Cm nativekernel
 104 Rebuild the kernel and the kernel-modules using native tools.
 105 .It Cm quickkernel
 106 Same as
 107 .Cm buildkernel ,
 108 but skip the depend step and do not clean out the
 109 obj modules.
 110 This target can be used for incremental upgrades once a full
 111 build of the kernel has been done with
 112 .Cm buildkernel .
 113 .It Cm installkernel
 114 Install the kernel and the kernel-modules.
 115 .It Cm reinstallkernel
 116 Reinstall the kernel and the kernel-modules.
 117 .It Cm kernel
 118 .Cm buildkernel +
 119 .Cm installkernel .
 120 .It Cm preupgrade
 121 Perform certain upgrades that have to be done before
 122 .Cm installworld .
 123 .Cm installworld
 124 will complain if they have not been done.
 125 .It Cm upgrade
 126 Upgrade the files in /etc and also setup the rest of the system for
 127 the version of
 128 .Dx
 129 just installed.
 130 .It Cm most
 131 Build user commands, no libraries or include files.
 132 .It Cm installmost
 133 Install user commands, no libraries or include files.
 134 .El
 135 .Sh ENVIRONMENT
 136 .Bl -tag -width ".Va TARGET_ARCH"
 137 .It Va TARGET_ARCH
 138 The target machine processor architecture.
 139 This is analogous to the
 140 .Dq Nm uname Fl p
 141 output.
 142 .\"Set this to cross-build for a different architecture.
 143 .It Va TARGET
 144 The target hardware platform.
 145 This is analogous to the
 146 .Dq Nm uname Fl m
 147 output.
 148 .\"This is necessary to cross-build some target architectures.
 149 .It Va NO_WERROR
 150 If defined, warnings will not cause the build to halt, even if the
 151 makefile says otherwise.
 152 .It Va DESTDIR
 153 The directory hierarchy where the resulting binaries will be
 154 installed.
 155 .It Va MAKEOBJDIRPREFIX
 156 The directory hierarchy where the object files will be built.
 157 .El
 158 .Sh FILES
 159 .Bl -tag -width ".Pa /usr/src/share/doc/Makefile" -compact
 160 .It Pa /etc/make.conf
 161 .It Pa /etc/defaults/make.conf
 162 .It Pa /usr/src/share/doc/Makefile
 163 .It Pa /usr/src/Makefile
 164 .It Pa /usr/src/Makefile.inc1
 165 .El
 166 .Sh EXAMPLES
 167 The
 168 .Dq approved
 169 method of updating your system from the latest sources is:
 170 .Bd -literal -offset indent
 171 make buildworld
 172 make buildkernel KERNCONF=FOO
 173 make installkernel KERNCONF=FOO
 174 make installworld
 175 make upgrade
 176 .Ed
 177 .Pp
 178 .Dq FOO
 179 must be replaced with the name of the kernel configuration file from which
 180 the kernel should be built.
 181 Alternatively, the
 182 .Va KERNCONF
 183 variable in
 184 .Pa /etc/make.conf
 185 can be set to the name of the kernel to build;
 186 in this case the
 187 .Dq KERNCONF=FOO
 188 part of the
 189 .Cm buildkernel
 190 and
 191 .Cm installkernel
 192 commands can be omitted.
 193 .Pp
 194 After running these commands a system reboot is required,
 195 otherwise many programs which have been rebuilt
 196 (such as
 197 .Nm ps ,
 198 .Nm top ,
 199 etc)
 200 may not work with the old kernel which is still running.
 201 .Sh CAVEATS
 202 The build and install order in the
 203 .Sx EXAMPLES
 204 section enforces that the new kernel is installed before the new
 205 world.
 206 Sometimes it might be necessary to reboot the system between those two
 207 steps.
 208 In this case the
 209 .Cm installworld
 210 target will tell you so.
 211 .Pp
 212 Also note that you should
 213 .Em never
 214 run the
 215 .Cm upgrade
 216 target before having installed the new kernel and world because your
 217 system might (in the worst case) be rendered useless if you do so.
 218 This can happen because
 219 .Cm upgrade
 220 might remove something that the old system still needs for
 221 functioning correctly.
 222 .Sh SEE ALSO
 223 .Xr cc 1 ,
 224 .Xr install 1 ,
 225 .Xr make 1 ,
 226 .Xr wmake 1 ,
 227 .Xr make.conf 5 ,
 228 .Xr packages 7 ,
 229 .Xr release 7 ,
 230 .Xr config 8 ,
 231 .Xr reboot 8 ,
 232 .Xr shutdown 8
 233 .Sh AUTHORS
 234 .An -nosplit
 235 .An Mike W. Meyer Aq mwm@mired.org
 236 and
 237 .An Sascha Wildner Aq swildner@gmail.com .