tools/build/options/makeman

   1 #!/bin/sh
   2 #
   3 # This file is in the public domain.
   4 # $FreeBSD$
   5 #
   6 # This script creates the src.conf.5 man page using template text contained
   7 # herein and the contents of the WITH_* and WITHOUT_* files in the same
   8 # directory. Each WITH_* and WITHOUT_* file documents the effect of the
   9 # /etc/src.conf knob with the same name.
  10 #
  11 # For each supported architecture, "make showconfig" is invoked to determine
  12 # the default setting of every option: always WITH_, always WITHOUT_, or
  13 # architecture-dependent WITH_/WITHOUT_.  It also determines and describes
  14 # dependencies between options.
  15 #
  16 # Usage:
  17 #
  18 #     cd tools/build/options
  19 #     sh makeman > ../../../share/man/man5/src.conf.5
  20
  21 set -o errexit
  22 export LC_ALL=C
  23
  24 t=$(mktemp -d -t makeman)
  25 trap 'test -d $t && rm -rf $t' exit
  26
  27 srcdir=$(realpath ../../..)
  28 make="make -C $srcdir -m $srcdir/share/mk"
  29
  30 #
  31 # usage: no_targets all_targets yes_targets
  32 #
  33 no_targets()
  34 {
  35         for t1 in $1 ; do
  36                 for t2 in $2 ; do
  37                         if [ "${t1}" = "${t2}" ] ; then
  38                                 continue 2
  39                         fi
  40                 done
  41                 echo ${t1}
  42         done
  43 }
  44
  45 show_options()
  46 {
  47         ALL_TARGETS=$(echo $(${make} targets | tail -n +2))
  48         rm -f $t/settings
  49         for target in ${ALL_TARGETS} ; do
  50                 prev_opt=
  51                 env -i ${make} showconfig \
  52                     SRC_ENV_CONF=/dev/null SRCCONF=/dev/null \
  53                     __MAKE_CONF=/dev/null \
  54                     TARGET_ARCH=${target#*/} TARGET=${target%/*} |
  55                 while read var _ val ; do
  56                         opt=${var#MK_}
  57                         if [ $opt = "$prev_opt" ]; then
  58                                 echo "$target: ignoring duplicate option $opt" >&2
  59                                 continue
  60                         fi
  61                         prev_opt=$opt
  62                         case ${val} in
  63                         yes)
  64                                 echo ${opt} ${target}
  65                                 ;;
  66                         no)
  67                                 echo ${opt}
  68                                 ;;
  69                         *)
  70                                 echo "make showconfig broken: ${var} ${_} ${val} (not yes or no)" >&2
  71                                 exit 1
  72                                 ;;
  73                         esac
  74                 done > $t/settings.target
  75                 if [ -r $t/settings ] ; then
  76                         join -t\  $t/settings $t/settings.target > $t/settings.new
  77                         mv $t/settings.new $t/settings
  78                 else
  79                         mv $t/settings.target $t/settings
  80                 fi
  81         done
  82
  83         while read opt targets ; do
  84                 if [ "${targets}" = "${ALL_TARGETS}" ] ; then
  85                         echo "WITHOUT_${opt}"
  86                 elif [ -z "${targets}" ] ; then
  87                         echo "WITH_${opt}"
  88                 else
  89                         echo "WITHOUT_${opt}" $(no_targets "${ALL_TARGETS}" "${targets}")
  90                         echo "WITH_${opt} ${targets}"
  91                 fi
  92         done < $t/settings
  93 }
  94
  95 #
  96 # usage: show { settings | with | without } ...
  97 #
  98 show()
  99 {
 100
 101         mode=$1 ; shift
 102         case ${mode} in
 103         settings)
 104                 yes_prefix=WITH
 105                 no_prefix=WITHOUT
 106                 ;;
 107         with)
 108                 yes_prefix=WITH
 109                 no_prefix=WITH
 110                 ;;
 111         without)
 112                 yes_prefix=WITHOUT
 113                 no_prefix=WITHOUT
 114                 ;;
 115         *)
 116                 echo 'internal error' >&2
 117                 exit 1
 118                 ;;
 119         esac
 120         env -i ${make} .MAKE.MODE=normal "$@" showconfig __MAKE_CONF=/dev/null \
 121             SRCCONF=/dev/null |
 122         while read var _ val ; do
 123                 opt=${var#MK_}
 124                 case ${val} in
 125                 yes)
 126                         echo ${yes_prefix}_${opt}
 127                         ;;
 128                 no)
 129                         echo ${no_prefix}_${opt}
 130                         ;;
 131                 *)
 132                         echo "make showconfig broken: ${var} ${_} ${val} (not yes or no)" >&2
 133                         exit 1
 134                         ;;
 135                 esac
 136         done
 137 }
 138
 139 main()
 140 {
 141         echo "building src.conf.5 man page from files in ${PWD}" >&2
 142
 143         fbsdid='$'FreeBSD'$'
 144         cat <<EOF
 145 .\" DO NOT EDIT-- this file is generated by tools/build/options/makeman.
 146 .\" ${fbsdid}
 147 .Dd $(echo $(LC_TIME=C date +'%B %e, %Y'))
 148 .Dt SRC.CONF 5
 149 .Os
 150 .Sh NAME
 151 .Nm src.conf
 152 .Nd "source build options"
 153 .Sh DESCRIPTION
 154 The
 155 .Nm
 156 file contains settings that will apply to every build involving the
 157 .Fx
 158 source tree; see
 159 .Xr build 7 .
 160 .Pp
 161 The
 162 .Nm
 163 file uses the standard makefile syntax.
 164 However,
 165 .Nm
 166 should not specify any dependencies to
 167 .Xr make 1 .
 168 Instead,
 169 .Nm
 170 is to set
 171 .Xr make 1
 172 variables that control the aspects of how the system builds.
 173 .Pp
 174 The default location of
 175 .Nm
 176 is
 177 .Pa /etc/src.conf ,
 178 though an alternative location can be specified in the
 179 .Xr make 1
 180 variable
 181 .Va SRCCONF .
 182 Overriding the location of
 183 .Nm
 184 may be necessary if the system-wide settings are not suitable
 185 for a particular build.
 186 For instance, setting
 187 .Va SRCCONF
 188 to
 189 .Pa /dev/null
 190 effectively resets all build controls to their defaults.
 191 .Pp
 192 The only purpose of
 193 .Nm
 194 is to control the compilation of the
 195 .Fx
 196 source code, which is usually located in
 197 .Pa /usr/src .
 198 As a rule, the system administrator creates
 199 .Nm
 200 when the values of certain control variables need to be changed
 201 from their defaults.
 202 .Pp
 203 In addition, control variables can be specified
 204 for a particular build via the
 205 .Fl D
 206 option of
 207 .Xr make 1
 208 or in its environment; see
 209 .Xr environ 7 .
 210 .Pp
 211 The environment of
 212 .Xr make 1
 213 for the build can be controlled via the
 214 .Va SRC_ENV_CONF
 215 variable, which defaults to
 216 .Pa /etc/src-env.conf .
 217 Some examples that may only be set in this file are
 218 .Va WITH_DIRDEPS_BUILD ,
 219 and
 220 .Va WITH_META_MODE
 221 as they are environment-only variables.
 222 Note that
 223 .Va MAKEOBJDIRPREFIX
 224 may be set here only when using
 225 .Va WITH_DIRDEPS_BUILD .
 226 .Pp
 227 The values of variables are ignored regardless of their setting;
 228 even if they would be set to
 229 .Dq Li FALSE
 230 or
 231 .Dq Li NO .
 232 The presence of an option causes
 233 it to be honored by
 234 .Xr make 1 .
 235 .Pp
 236 This list provides a name and short description for variables
 237 that can be used for source builds.
 238 .Bl -tag -width indent
 239 EOF
 240         show settings SRC_ENV_CONF=/dev/null | sort > $t/config_default
 241         # Work around WITH_LDNS_UTILS forcing BIND_UTILS off by parsing the
 242         # actual config that results from enabling every WITH_ option.  This
 243         # can be reverted if/when we no longer have options that disable
 244         # others.
 245         show with SRC_ENV_CONF=/dev/null | sort | sed 's/$/=/' > $t/src.conf
 246         show settings SRC_ENV_CONF=$t/src.conf | sort > $t/config_WITH_ALL
 247         show without SRC_ENV_CONF=/dev/null | sort > $t/config_WITHOUT_ALL
 248         env_only_options="$(${make} -V __ENV_ONLY_OPTIONS)"
 249
 250         show_options |
 251         while read opt targets ; do
 252                 if [ ! -f ${opt} ] ; then
 253                         echo "no description found for ${opt}, skipping" >&2
 254                         continue
 255                 fi
 256
 257                 echo ".It Va ${opt}"
 258                 sed -e'/\$FreeBSD.*\$/d' ${opt}
 259                 if [ -n "${targets}" ] ; then
 260                         echo '.Pp'
 261                         echo 'This is a default setting on'
 262                         echo $(echo ${targets} | sed -e's/ /, /g' -e's/\(.*\), /\1 and /').
 263                 fi
 264
 265                 if [ "${opt%%_*}" = 'WITHOUT' ] ; then
 266                         sed -n "/^WITH_${opt#WITHOUT_}$/!s/$/=/p" $t/config_WITH_ALL > $t/src.conf
 267                         show settings SRC_ENV_CONF=$t/src.conf -D${opt} | sort > $t/config_WITH_ALL_${opt}
 268                         comm -13 $t/config_WITH_ALL $t/config_WITH_ALL_${opt} | sed -n "/^${opt}$/!p" > $t/deps
 269                 elif [ "${opt%%_*}" = 'WITH' ] ; then
 270                         sed -n "/^WITHOUT${opt#WITH}$/!s/$/=/p" $t/config_WITHOUT_ALL > $t/src.conf
 271                         show settings SRC_ENV_CONF=$t/src.conf -D${opt} | sort > $t/config_WITHOUT_ALL_${opt}
 272                         comm -13 $t/config_WITHOUT_ALL $t/config_WITHOUT_ALL_${opt} | sed -n "/^${opt}$/!p" > $t/deps
 273                 else
 274                         echo 'internal error' >&2
 275                         exit 1
 276                 fi
 277
 278                 show settings SRC_ENV_CONF=/dev/null -D${opt} | sort > $t/config_${opt}
 279                 comm -13 $t/config_default $t/config_${opt} | sed -n "/^${opt}$/!p" |
 280                 comm -13 $t/deps - > $t/deps2
 281
 282                 havedeps=0
 283                 if [ -s $t/deps ] ; then
 284                         havedeps=1
 285                         echo 'When set, it enforces these options:'
 286                         echo '.Pp'
 287                         echo '.Bl -item -compact'
 288                         while read opt2 ; do
 289                                 echo '.It'
 290                                 echo ".Va ${opt2}"
 291                         done < $t/deps
 292                         echo '.El'
 293                 fi
 294
 295                 if [ -s $t/deps2 ] ; then
 296                         if [ ${havedeps} -eq 1 ] ; then
 297                                 echo '.Pp'
 298                         fi
 299                         echo 'When set, these options are also in effect:'
 300                         echo '.Pp'
 301                         echo '.Bl -inset -compact'
 302                         while read opt2 ; do
 303                                 echo ".It Va ${opt2}"
 304                                 noopt=$(echo ${opt2} | sed -e's/WITH_/WITHOUT_/;t' -e's/WITHOUT_/WITH_/')
 305                                 echo '(unless'
 306                                 echo ".Va ${noopt}"
 307                                 echo 'is set explicitly)'
 308                         done < $t/deps2
 309                         echo '.El'
 310                 fi
 311
 312                 case " ${env_only_options} " in
 313                         *\ ${opt#*_}\ *)
 314                                 echo ".Pp"
 315                                 echo "This must be set in the environment, make command line, or"
 316                                 echo ".Pa /etc/src-env.conf ,"
 317                                 echo "not"
 318                                 echo ".Pa /etc/src.conf ."
 319                                 ;;
 320                 esac
 321
 322                 twiddle >&2
 323         done
 324         cat <<EOF
 325 .El
 326 .Sh FILES
 327 .Bl -tag -compact -width Pa
 328 .It Pa /etc/src.conf
 329 .It Pa /etc/src-env.conf
 330 .It Pa /usr/share/mk/bsd.own.mk
 331 .El
 332 .Sh SEE ALSO
 333 .Xr make 1 ,
 334 .Xr make.conf 5 ,
 335 .Xr build 7 ,
 336 .Xr ports 7
 337 .Sh HISTORY
 338 The
 339 .Nm
 340 file appeared in
 341 .Fx 7.0 .
 342 .Sh AUTHORS
 343 This manual page was autogenerated by
 344 .An tools/build/options/makeman .
 345 EOF
 346 }
 347
 348 twiddle_pos=0
 349 twiddle()
 350 {
 351         local c0='|' c1='/' c2='-' c3='\'
 352
 353         eval printf '%c\\b' '$c'${twiddle_pos}
 354         twiddle_pos=$(((twiddle_pos+1)%4))
 355 }
 356
 357 main