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