usr.bin/dsynth/dsynth.1

   1 .\"
   2 .\" Copyright (c) 2020 The DragonFly Project.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to The DragonFly Project
   5 .\" by Matthew Dillon <dillon@backplane.com>
   6 .\" This code is based on a concept originally developed by John R. Marino.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\" 3. Neither the name of The DragonFly Project nor the names of its
  19 .\"    contributors may be used to endorse or promote products derived
  20 .\"    from this software without specific, prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  25 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  26 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  27 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  28 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  29 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  30 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  31 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  32 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .Dd October 24, 2019
  36 .Dt DSYNTH 1
  37 .Os
  38 .Sh NAME
  39 .Nm dsynth
  40 .Nd dsynth bulk dports builder utility
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl dhvxyDSN
  44 .Op Fl p Ar profile
  45 .Op Fl s Ar n
  46 .Op Fl m Ar gb
  47 .Ar directive
  48 .Op origins
  49 .Nm
  50 .Ar help
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 utility allows a user to build and maintain part or all of dports
  55 locally.
  56 .Nm
  57 figures out the dependency topology of the dport(s) for you and
  58 is capable of building any number of ports concurrently based
  59 on the configuration parameters you supply.
  60 .Pp
  61 also detects changes made to the ports tree and rebuilds packages
  62 and anything that depends on those packages as needed.
  63 .Pp
  64 .Nm
  65 is based on an application called
  66 .Xr synth 1
  67 which was written by John Marino in Ada and served as the conceptual base
  68 for this program.
  69 .Nm
  70 is written in C and designed to be as portable as possible given a
  71 ports-style infrastructure.
  72 .Pp
  73 Our recommended build topology is with a configuration as follows:
  74 .Bd -literal
  75 [Global Configuration]
  76 profile_selected= LiveSystem
  77
  78 [LiveSystem]
  79 Operating_system= DragonFly
  80 Directory_packages= /build/synth/live_packages
  81 Directory_repository= /build/synth/live_packages/All
  82 Directory_portsdir= /build/synth/dports
  83 Directory_options= /build/synth/options
  84 Directory_distfiles= /build/synth/distfiles
  85 Directory_buildbase= /build/synth/build
  86 Directory_logs= /build/synth/logs
  87 Directory_ccache= disabled
  88 Directory_system= /
  89 Package_suffix= .txz
  90 Number_of_builders= 8
  91 Max_jobs_per_builder= 8
  92 Display_with_ncurses= true
  93 .Ed
  94 .Pp
  95 This places all major directories under
  96 .Pa /build/synth .
  97 If you want to use the same dports and the same distfiles as your base
  98 system, you can null-mount /usr/distfiles onto /build/synth/distfiles
  99 and /usr/dports onto /build/synth/dports with
 100 .Pa /etc/fstab
 101 entries as follows:
 102 .Bd -literal
 103 # Device              Mountpoint                FStype  Options DumpPass#
 104 /usr/distfiles        /build/synth/distfiles    null    rw      4 4
 105 /usr/dports           /build/synth/dports       null    rw      4 4
 106 .Ed
 107 .Pp
 108 Please set the number of builders and the maximum number of jobs per
 109 builder according to available system resources.
 110 Remember that the total
 111 load on the system can be as high as (builders x jobs), and at least 4x
 112 that value in processes.
 113 Systems are typically restricted by memory and CPU horsepower.
 114 Start conservative and ramp up according to what your system can handle.
 115 A good rule of thumb is to set workers to the number of CPU threads your
 116 machine has or to 1/2 the number of gigabytes of memory your system has,
 117 whichever is lower.
 118 Then set the jobs per worker to no more than the
 119 number of CPU threads your machine has.
 120 .Pp
 121 .Nm
 122 has numerous features to manage machine load and swap usage to
 123 prevent a machine from being overloaded, allowing more workers
 124 to be configured than you might otherwise think is reasonable
 125 (which helps a lot when building the smaller ports).
 126 However, users running this program should be aware that very high loads
 127 and modest swap use are still likely to develop when building a large
 128 number of ports or when building very large ports like chromium.
 129 If the system is not dedicated to building packages you can reduce the
 130 impact to the rest of the system by running
 131 .Nm
 132 at nice +20 and also by reducing the number of workers and number of
 133 jobs per worker somewhat.
 134 .Pp
 135 We recommend that a minimum of 64GB of SSD-based swap be configured,
 136 or twice as much swap as main memory, whichever is the higher value.
 137 .Pp
 138 We recommend a minimum of 500GB of storage be configured in
 139 .Pa /build
 140 or wherever you have configured various directories.
 141 A full set of distfiles requires at least 120GB, a full dports including
 142 the git repo requires at least 1.5GB, and a full set of built packages
 143 requires at least 75GB.
 144 If using a filesystem such as HAMMER or HAMMER2
 145 which frees space overnight, double all of those numbers.
 146 .Pp
 147 The actual build infrastructure uses tmpfs... memory and swap, and does
 148 not use regular filesystem space.
 149 .Sh OPTIONS
 150 .Bl -tag -width indent
 151 .It Fl d[d...]
 152 Run in debug mode.
 153 If specified two or more times this will turn off
 154 ncurses and output the primary log (00_last_results.log) to the standard
 155 output, along with additional spew.
 156 .It Fl h
 157 Quickly output a synopsis of options and directives and exit.
 158 .It Fl m Ar gb
 159 Override the default package dependency memory target, in gigabytes.
 160 The default is 1/2 physical memory.
 161 The number of workers will be limited
 162 such that the aggregate size of package dependencies installed in each
 163 worker slot does not exceed this value.
 164 .Pp
 165 This handles a well-known effect where the sheer amount of data that has
 166 to be installed in tmpfs filesystems for large ports, when multiplied by
 167 the number of worker slots, can force excessive paging to occur and leave
 168 preciously little memory available to actually run compiles.
 169 Some paging
 170 is necessary to maintain maximum CPU utilization, but excessive paging
 171 can cause the whole machine to essentially become idle for extended
 172 periods of time.
 173 .It Fl v
 174 Quickly output the version and exit.
 175 .It Fl x
 176 .It Fl xx
 177 Normally dsynth builds a package for any of three reasons: (1) If the contents
 178 of the ports directory changes, (2) If anything the port depends on requires
 179 rebuilding so to will the port be rebuilt, (3) If there is no binary package
 180 already built for the port.
 181 .Pp
 182 If this option is specified, the first test is ignored.  If this
 183 option is specified twice, the first and second tests are ignored.
 184 .It Fl y
 185 Automatically answer 'y'es to any questions.
 186 .It Fl p Ar profile
 187 Override the global profile default in
 188 .Pa /etc/dsynth/dsynth.ini ,
 189 allowing you to trivially run whatever profile you like without having to
 190 edit the configuration file when switching.
 191 In addition, you can now run any number of dsynth's concurrently on the same
 192 machine without having to use a jail, each with a different profile,
 193 as long as the packages, repository, buildbase, and logs directories
 194 are different.
 195 .Pp
 196 Note that the distfiles directory can be shared and will not conflict
 197 or get confused with concurrent fetches.
 198 .It Fl s Ar n
 199 .Nm
 200 usually slow-starts the worker slots, beginning with one slot and increasing
 201 by one every 5 seconds until the maximum configured number of workers is
 202 reached.
 203 This gives
 204 .Nm
 205 a slower ramp that it can load manage against.
 206 Specifying 0 disables the slow-start feature and the maximum number of
 207 worker slots (limited by the dependency graph) will be loaded immediately.
 208 .It Fl D
 209 Turn on DEVELOPER mode when building ports.
 210 .It Fl S[S]
 211 Turn off curses for script friendliness.
 212 The output will be log 00 and
 213 should be redirected to /dev/null or something similar.
 214 If you supply the options twice, color output escapes will also be
 215 turned off.
 216 You may also wish to use the
 217 .Fl y
 218 option for scripting dsynth.
 219 .It Fl N
 220 Normally
 221 .Nm
 222 nices its sub-processes to +10.
 223 This option disables the feature.
 224 .El
 225 .Sh DIRECTIVES
 226 Generally
 227 .Nm
 228 is run with a directive and some directives allow a list of ports to be
 229 specified.
 230 This list should be space-delimited in DIR/SUBDIR format, for example:
 231 .Ar www/chromium .
 232 For directives with an optional ports list, your current installed set
 233 of ports will be used if you do not specify a list.
 234 .Bl -tag -width indent
 235 .It Cm status
 236 This will do a dry-run of
 237 .Cm upgrade-system
 238 but not actually build anything.
 239 .It Cm cleanup
 240 This will clean up any left-over mounts from prior builds.
 241 .Nm
 242 attempts to clean up all processes and mounts when you interrupt
 243 a build but doesn't always succeed.
 244 .It Cm init
 245 Creates and initializes the
 246 .Pa /etc/dsynth
 247 directory if it does not exst.
 248 This directive will complain and exit if either
 249 .Pa /etc/dsynth
 250 or
 251 .Pa /usr/local/etc/dsynth
 252 exists.
 253 It will not create
 254 .Pa /etc/dsynth
 255 in this situation.
 256 .It Cm configure
 257 NOT CURRENTLY IMPLEMENTED
 258 .It Cm upgrade-system
 259 NOT CURRENTLY IMPLEMENTED.
 260 Incrementally build and upgrade your locally
 261 installed packages, then upgrade your local system with them.
 262 .It Cm prepare-system
 263 Incrementally build and upgrade your locally installed packages, but
 264 do not upgrade your system with them.
 265 .It Cm rebuild-repository
 266 Build or rebuild the database files for the configured repository.
 267 .It Cm purge-distfiles
 268 Delete any obsolete source distribution files.
 269 .It Cm reset-db
 270 Delete ports_crc.db from the build directory.  This database is used
 271 to detect changes made to the dports tree.  It will be regenerated
 272 on your next build without forcing any packages to be rebuilt.
 273 .It Cm status-everything
 274 This will do a dry-run of a full bulk build of everything,
 275 but not actually build anything.
 276 .It Cm everything
 277 This will build the entire dports tree and then rebuild the repository
 278 when it finishes.
 279 .It Cm version
 280 This is for synth compatibility.
 281 The version of
 282 .Nm
 283 will be printed and the program will exit.
 284 .It Cm help
 285 Output a synopsis of options and directives and exit.
 286 .It Cm status Op Ar ports
 287 Do a dry-run with 'build' of the given list.
 288 .It Cm build Op Ar ports
 289 Incrementally build dports based on the given list.
 290 When done, ask whether the repository should be rebuilt or not.
 291 .It Cm just-build Op Ar ports
 292 Incrementally build dports based on the given list, then
 293 exits.
 294 No post-build steps will be taken.
 295 .It Cm install Op Ar ports
 296 NOT CURRENTLY IMPLEMENTED.  'build' based on the supplied
 297 list (or using currently installed packages), then rebuild
 298 the repository and upgrade the system without asking any further
 299 questions.
 300 .It Cm force Op Ar ports
 301 This is the same as 'build' but will delete existing packages first.
 302 Dependencies are not deleted unless they are out of date.
 303 .It Cm test Op Ar ports
 304 This is the same as 'build' but sets the environment variable
 305 .Ev DEVELOPER
 306 to
 307 .Sq yes
 308 and pre-deletes specified packages.
 309 Dependencies are not deleted unless they are out of date.
 310 .It Cm debug Op Ar ports
 311 This is the same as 'build' but leaves the chroot mounts intact
 312 upon completion.
 313 .El
 314 .Sh FILES
 315 .Bl -tag -width ".It Pa <fs>/abc/defghi/<name>" -compact
 316 .It Pa /etc/dsynth/dsynth.ini
 317 The primary configuration file.
 318 If not found,
 319 .Nm
 320 will also look in
 321 .Pa /usr/local/etc/dsynth/dsynth.ini .
 322 .Pp
 323 .It Pa /etc/dsynth/LiveSystem-make.conf
 324 Typically contains the environment variables that will be set in
 325 the workers.
 326 .Nm
 327 firewalls the environment it is run under from the environment it
 328 provides to the workers.
 329 .Pp
 330 .It Pa /build/synth/build
 331 Recommended setting for
 332 .Va Directory_buildbase ,
 333 contains the build infrastructure... typically a template, mirrored
 334 system directories, and mount points for all the worker slots.
 335 The template will be [re]generated if 'pkg' needs to be built or
 336 if the
 337 .Pa .template.good
 338 file in this directory is deleted.
 339 .Pp
 340 .It Pa /build/synth/distfiles
 341 Recommended setting for
 342 .Va Directory_distfiles ,
 343 ports to a directory into which
 344 .Nm
 345 will download any source distribution files required for building.
 346 .Pp
 347 .It Pa /build/synth/dports
 348 Recommended setting for
 349 .Va Directory_portsdir ,
 350 points to a checked out dports repo.
 351 Note that
 352 .Nm
 353 does not automatically 'git pull' or otherwise synchronize the dports repo,
 354 you must do that yourself prior to starting a build.
 355 .Pp
 356 .It Pa /build/synth/live_packages
 357 Recommended setting for
 358 .Va Directory_packages ,
 359 points to a directory which will contain the completed application
 360 packages.
 361 .Pp
 362 .It Pa /build/synth/logs
 363 Recommended setting for
 364 .Va Directory_logs ,
 365 all log files will be placed in this directory.
 366 Special management logfiles begin with the numeral '0' for easily
 367 location.
 368 The logfiles for ports while and after building are stored in the
 369 form subdir____portname.log, with three underscores.
 370 .Pp
 371 .It Pa /build/synth/options
 372 Recommended setting for
 373 .Va Directory_options ,
 374 where options overrides for specific ports may be located.
 375 .Pp
 376 .It Pa /
 377 Recommended setting for
 378 .Va Directory_system ,
 379 which
 380 .Nm
 381 uses as a basis for creating the jails or chroots in each worker slot
 382 during building.
 383 No part of the system root is ever NULL-mounted read-write... it is always
 384 NULL-mounted read-only.
 385 Some elements from the system base will be mirrored in the build-base
 386 as an optimization.
 387 .Pp
 388 Note that the packages directory and the distfiles directory is mounted
 389 read-write in jails or chroots.
 390 All other r/w filesystems in the workers are
 391 .Xr tmpfs 5
 392 based filesystems and will be created and torn-down for each port.
 393 .Pp
 394 .It Pa .txz
 395 .It Pa .tgz
 396 .It Pa .tar
 397 .It Pa .tbz
 398 The recommended setting for
 399 .Va Package_suffix
 400 is either
 401 .Pa .txz
 402 or
 403 .Pa .tgz .
 404 Use
 405 .Pa .txz
 406 for better compression at the cost of somewhat slower bulk builds due
 407 to the time overhead for compression and decompression, or
 408 use
 409 .Pa .tgz
 410 for modest compression and very fast compression and decompression.
 411 Due to the way the builder works, package dependencies are fresly
 412 installed into the chroot slot for each package being built, so
 413 decompression time matters.
 414 .El
 415 .Sh EXIT STATUS
 416 .Ex -std
 417 .Sh SEE ALSO
 418 .Xr synth 1 ,
 419 .Xr dports 7
 420 .Sh HISTORY
 421 The
 422 .Nm
 423 utility first appeared in
 424 .Dx 5.7 .
 425 .Sh AUTHORS
 426 .An Matthew Dillon Aq Mt dillon@backplane.com