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