1KDESRC-BUILD(1)                KDE User's Manual               KDESRC-BUILD(1)
2
3
4

NAME

6       kdesrc-build - Downloads, builds and installs KDE software.
7

SYNOPSIS

9       kdesrc-build [OPTIONS...] [Module name | Module set name...]
10

DESCRIPTION

12       The kdesrc-build command is used in order to build KDE software
13       directly from its source repositories. It can download from Subversion
14       or Git repositories, interfaces with the KDE project database, and
15       supports controlling which options are passed to make(1) and cmake(1).
16       The operation of kdesrc-build is driven by a configuration file,
17       typically ~/.kdesrc-buildrc.
18
19       The module name or module set name as given on the command line should
20       be as those names were defined in the configuration file (either in a
21       module definition or use-modules declaration, or in a module-set
22       definition). In addition, it can be the name of a KDE module listed in
23       the KDE project database (and you can precede the module name with + to
24       force this).
25
26       kdesrc-build is designed to be able to be completely headless (however,
27       see ENVIRONMENT), and so typically ignores its input completely.
28       Command output is logged instead of being shown on the kdesrc-build
29       output.
30
31       Modules are built one after the other. If a module fails to update then
32       it is not built.  kdesrc-build will not abort just because of a module
33       failure, instead it will keep trying to update and build subsequent
34       modules. By default, kdesrc-build will commence building a module as
35       soon as the source code update is complete for that module, even if
36       other updates are occurring concurrently.
37
38       At the end kdesrc-build will show which modules failed to build, and
39       where the logs were kept for that build run.
40

OPTIONS

42       NOTE: Some options have short forms, but the kdesrc-build option parser
43       does not support combining short options into one at this point. (E.g.
44       running kdesrc-build -pv would not be the same as kdesrc-build
45       --pretend --verbose).
46
47       -h, --help
48           Shows a brief synopsis and frequently-used command line options.
49
50       -p, --pretend
51           Operate in a "dry run" mode. No network accesses are made, no log
52           files are created, no modules are built, and no other permanent
53           changes to disk are made. One important exception is that if you
54           try to build a module that comes from the KDE project database, and
55           the database hasn't been downloaded yet, the database will be
56           downloaded since the pretend-mode output may change significantly
57           based on the database results.
58
59       --install
60           Skips the update and build phase and immediately attempts to
61           install the modules given.
62
63       --uninstall
64           Skips the update and build phase and immediately attempts to
65           uninstall the modules given.  NOTE: This is only supported for
66           buildsystems that supports the make uninstall command (e.g.  KDE
67           CMake-based).
68
69       --no-src
70           Skips the source update phase. Other phases are included as normal.
71           --no-svn is a deprecated alias for this option and will be removed
72           in a future release.
73
74       --no-install
75           Skips the install phase from the build. Other phases are included
76           as normal.
77
78       --no-build
79           Skips the build phase for the build. Internally the install phase
80           depends on the build phase completing so this is effectively
81           equivalent to --src-only, but the semantics may change in the
82           future (e.g. when test suites are moved into their own phase).
83
84       --no-tests
85           Disables running the test suite for CMake-based modules. To be
86           fully effective this requires re-running CMake, which can be forced
87           by using the --reconfigure or --refresh-build options.
88
89       --src-only
90           Only performs the source update phase, does not build or install.
91           --svn-only is a deprecated alias for this option and will be
92           removed in a future release.
93
94       --build-only
95           Forces the build process to be performed without updating source
96           code first. In addition, installation is not performed. (Testing is
97           still performed if applicable, but this will change in a future
98           release)
99
100       --refresh-build
101           Removes the build directory for a module before the build phase
102           starts. This has the desired side effect of forcing kdesrc-build to
103           re-configure the module and build it from a "pristine" state with
104           no existing temporary or intermediate output files. Use this option
105           if you have problems getting a module to build but realize it will
106           take longer (possibly much longer) for the build to complete as a
107           result. When in doubt use this option for the entire kdesrc-build
108           run.
109
110       --reconfigure
111           Force CMake to be re-run, but without deleting the build directory.
112           Usually you actually want --refresh-build, but if you are 100% sure
113           your change to cmake-options will not invalidate your current
114           intermediate output then this can save some time.
115
116       --build-system-only
117           Interrupts the build process for each module built: The build
118           process consists of normal setup up to and including running cmake
119           or configure (as appropriate), but make is not run and no
120           installation is attempted. This is mostly only useful to get things
121           like configure --help and cmake-gui to work. Normally you want
122           --reconfigure or --refresh-build.
123
124       --resume-from=foo
125           Use this option to skip module processing until the module foo is
126           encountered.  foo and all subsequent modules will be processed
127           normally as if they had been specified on the command line. If you
128           use this option because of a build failure you may want to consider
129           using --no-src in addition to skip the resultant source update
130           phase.
131
132       --resume-after=foo
133           This is just like --resume-from, except that the module foo is not
134           included in the list of modules to consider. You might use this if
135           you've manually built/installed foo after fixing the build and just
136           want to resume from there.
137
138       --ignore-modules
139           Forces ALL modules that follow this option to be excluded from
140           consideration by kdesrc-build. This might be useful if you know you
141           want to process all modules except for specific exceptions.
142
143       --rc-file=foo
144           Use the given file, foo, for the configuration instead of
145           ~/.kdesrc-buildrc or ./kdesrc-buildrc. The file can be empty, but
146           must exist.
147
148       --prefix=foo
149           Overrides the kdedir setting to be foo for this run. In addition,
150           implies --reconfigure. It does not actually perform the action you
151           would think it does (overriding the prefix option to change where
152           modules are installed), although by default modules are installed
153           to the kdedir setting if prefix is not set.
154
155       --nice=foo
156           Changes the CPU priority given to kdesrc-build (and all processes
157           used by kdesrc-build e.g.  make(1)).  foo should be an integer
158           number between -20 and 19. Positive values are "nicer" to the rest
159           of the system (i.e. lower priority).
160
161           Note that the possible priorities available on your system may be
162           different than listed here, see nice(2) for more information. Note
163           also that this only changes CPU priority, often you want to change
164           I/O priority on systems where that is supported. There is no
165           command-line option for I/O priority adjustment, but there is a
166           configuration file option: use-idle-io-priority (although like all
167           options, there is a generic way to set this from the command line).
168
169       --run=foo
170           Runs the program named by foo using kdesrc-build's normal build
171           environment. All command line arguments present after this option
172           are passed to foo as it is run.
173
174       --color
175           Enables "colorful output". (Enabled by default).
176
177       --no-color
178           Disables "colorful output". This can be made permanent by setting
179           the colorful-output option to false (or 0) in your configuration
180           file.
181
182       --async
183           Have kdesrc-build start the build process for a module as soon as
184           the source code has finished downloading. Without this option
185           kdesrc-build performs all source updates at once and only then
186           starts with the build process. This option is enabled by default.
187
188       --no-async
189           Disables asynchronous building of modules. See --async for a more
190           detailed description. Note that kdesrc-build's output will be
191           slightly different in this mode.
192
193       -v, --verbose
194           Increases the level of verbosity of kdesrc-build output (which is
195           already fairly verbose!)
196
197       -q, --quiet
198           Makes kdesrc-build less noisy. Only important messages are shown.
199
200       --really-quiet
201           Makes kdesrc-build even less noisy. Only warnings/errors are shown.
202
203       --debug
204           This will fill your terminal with descriptions and debugging
205           output, usually unintelligible, describing what kdesrc-build is
206           doing (and thinks it should be doing). The flag is included since
207           the output may sometimes prove useful for debugging.
208
209       --force-build
210           Normally when kdesrc-build notices that there is no source update
211           on a module which was previously successfully installed, it does
212           not attempt to build or install that module. You can pass this flag
213           to disable that behavior and always run make.
214
215       --no-snapshots
216           Normally kdesrc-build supports using source repository tarball
217           snapshots to reduce load on KDE infrastructure for git clones for
218           some KDE modules. Passing this option disables this feature.
219
220       --delete-my-patches
221           This option must be passed to allow kdesrc-build to remove
222           conflicting source directories. Currently even this only happens
223           when trying to clone a git-based module if an existing source
224           directory is present. Never specify this option unless it is
225           suggested by kdesrc-build, and only if you don't mind the source
226           directories that are referenced being deleted and re-cloned.
227
228       --foo=bar
229           Any option not listed above is checked to see if it matches the
230           list of possible configuration file options. If so, the
231           configuration file option foo is temporarily set to bar for the
232           duration of this run.
233
234       --module,foo=bar
235           Like above, but option foo is only set to bar for the module
236           module. This does not work for module sets yet, you must repeat
237           this for each module you want to be affected. (Of course, you could
238           simply edit your configuration file...)
239

EXIT STATUS

241       0
242           Success
243
244       1
245           Normally this means some part of the update, build or install
246           process failed, but is also used for any abnormal program end not
247           otherwise covered below.
248
249       5
250           A signal was received that killed kdesrc-build, but it attempted to
251           perform normal closedown.
252
253       8
254           Unknown option was passed on the command line.
255
256       99
257           An exception was raised that forced kdesrc-build to abort early.
258

ENVIRONMENT

260       HOME
261           Used for tilde-expansion of file names, and is the default base for
262           the source, build, and installation directories.
263
264       PATH
265           This environment variable controls the default search path for
266           executables. You can use the binpath configuration file option to
267           add to this variable (e.g. for running from cron(8)).
268
269       LC_*
270           Environment variables starting with LC_ control the locale used by
271           kdesrc-build. Although kdesrc-build is still not localizable at
272           this point, many of the commands it uses are.  kdesrc-build
273           normally sets LC_ALL=C for commands that its must examine the
274           output of but you can manually do this as well. If setting LC_ALL=C
275           fixes a kdesrc-build problem please submit a bug report.
276
277       SSH_AGENT_PID
278           This environment variable is checked to see if ssh-agent(1) is
279           running, but only if kdesrc-build determines that you are checking
280           out a module that requires an SSH login (but you should know this
281           as no module requires this by default).
282
283       KDESRC_BUILD_USE_TTY
284           If set, this variable forces kdesrc-build not to close its input
285           while executing system processes. Normally kdesrc-build closes
286           stdin since the stdout and stderr for its child processes are
287           redirected and therefore the user would never see an input prompt
288           anyways.
289
290       KDESRC_BUILD_DUMP_CONTEXT
291           If set, this variable prints out a description of its "build
292           context" just after reading options and command line arguments and
293           determining which modules to build. You pretty much never want to
294           set this.
295
296       others
297           Many programs are used by kdesrc-build in the course of its
298           execution, including svn(1), git(1), make(1), and cmake(1). Each of
299           these programs may have their own response to environment variables
300           being set.  kdesrc-build will pass environment variables that are
301           set when it is run onto these processes. You can ensure certain
302           environment variables (e.g.  CC or CXX) are set by using the
303           set-env configuration file option.
304

FILES

306       ~/.kdesrc-buildrc - Default global configuration file.
307
308       ./kdesrc-buildrc - If this file (note there is no leading period (.)
309       this time) is found in the current directory when kdesrc-build is run,
310       this file will be used for the configuration instead of
311       ~/.kdesrc-buildrc.
312
313       ~/.kdesrc-build-data - kdesrc-build uses this file to store persistent
314       data (such as last CMake options used, last revision successfully
315       installed, etc.). It can be safely deleted.
316

BUGS

318       See http://bugs.kde.org/. Be sure to search against the kdesrc-build
319       product.
320

EXAMPLE

322       $ kdesrc-build
323           Downloads, builds and installs all modules listed in the
324           configuration file, in the order defined therein.
325
326       $ kdesrc-build --pretend
327           Same as above, except no permanent actions are taken (specifically
328           no log files are created, downloads performed, build processes run,
329           etc.).  EXCEPTION: If you are trying to build a module defined in
330           the KDE project database, and the database has not been downloaded
331           yet, kdesrc-build will download the database since this can
332           significantly affect the final build order.
333
334       $ kdesrc-build --no-src --refresh-build kdebase
335           Deletes the build directory for the kdebase module set
336           (--refresh-build) and then starts the build process again without
337           updating the source code in-between.
338
339       $ kdesrc-build --rc-file /dev/null --pretend
340           Forces kdesrc-build to read an empty configuration file and
341           simulate the resultant build process. This shows what would happen
342           by default with no configuration file, without an error message
343           about a missing configuration file.
344
345       $ kdesrc-build +kdebase/kde-baseapps
346           Downloads, builds and installs the kde-baseapps module from the KDE
347           project database. Since the module name is preceded by a + it is
348           assumed to defined in the KDE project database even if this hasn't
349           been specifically configured in the configuration file.
350
351           The kdebase/ portion forces kdesrc-build to ignore any kde-baseapps
352           modules that are not children of the kdebase supermodule in the
353           project database (although it is contrived for this example).
354
355       $ kdesrc-build --refresh-build
356       --cmake-options="-DCMAKE_BUILD_TYPE=Debug"
357           Downloads, builds and installs all modules defined in the
358           configuration file but overrides the cmake-options option to have
359           the value given on the command line for this run only. Any further
360           kdesrc-build runs will use the cmake-options given in the
361           configuration file.
362

SEE ALSO

364       build-tool - A program by Michael Jansen which can build KDE software
365       based on included recipes.
366

RESOURCES

368       Main web site: http://kdesrc-build.kde.org/
369
370       Documentation: http://kdesrc-build.kde.org/documentation/
371
372       Setup script: kdesrc-build-setup
373

COPYING

375       Copyright (C) 2003-2011 Michael Pyne.
376
377       This program is free software; you can redistribute it and/or modify it
378       under the terms of the GNU General Public License as published by the
379       Free Software Foundation; either version 2 of the License, or (at your
380       option) any later version.
381
382       This program is distributed in the hope that it will be useful, but
383       WITHOUT ANY WARRANTY; without even the implied warranty of
384       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
385       General Public License for more details.
386
387       You should have received a copy of the GNU General Public License along
388       with this program; if not, write to the Free Software Foundation, Inc.,
389       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
390

AUTHOR

392       Michael Pyne <mpyne@kde.org>
393           Author.
394
395
396
3971.15.1                            2012-05-21                   KDESRC-BUILD(1)
Impressum