[sdk/kdesrc-build] doc: doc: supported-cmdline-params - separate docbook
Git commit d3ebb4f33fd0db60abf28d4cdb41058cfb3284cd by Andrew Shark. Committed on 05/01/2024 at 20:00. Pushed by ashark into branch 'master'. doc: supported-cmdline-params - separate docbook M +1-724 doc/cmdline.docbook M +1-0doc/index.docbook C +0-113 doc/supported-cmdline-params.docbook [from: doc/cmdline.docbook - 086% similarity] https://invent.kde.org/sdk/kdesrc-build/-/commit/d3ebb4f33fd0db60abf28d4cdb41058cfb3284cd diff --git a/doc/cmdline.docbook b/doc/cmdline.docbook index ecec619f..4273c346 100644 --- a/doc/cmdline.docbook +++ b/doc/cmdline.docbook @@ -109,729 +109,6 @@ linkend="conf-set-env">set-env option. - -Supported command-line parameters - - -The script accepts the following command-line options: - - - - - ---async - -Enables the asynchronous mode, which can -perform the source code updates and module builds at the same time. This is -the default, this option only needs specified if you have disabled it in the -configuration. - - - - ---help (or -h) - -Only display simple help on this script. - - - - ---version (or -v) - -Display the program version. - - - - ---show-info - -Displays information about and the operating system, that may -prove useful in bug reports or when asking for help in forums or mailing lists. - -Available since version 18.11. - - - - ---initial-setup - -Has perform the one-time initial setup necessary to prepare -the system for to operate, and for the newly-installed -software to run. - -This includes: - -Installing known dependencies (on supported distributions) -Adding required environment variables to ~/.bashrc -Setting up a configuration file - -This option is exactly equivalent to using ---install-distro-packages ---generate-config ---update-shellrc at the same time. - - - - - ---install-distro-packages - -Installs distro packages (on supported distributions) necessary to prepare the system for to operate, and for the newly-installed -software to run. - -See also --initial-setup - - - - ---generate-config - -Generate the configuration file. - -See also --initial-setup - - - - ---update-shellrc - -Edit the "~/.bashrc" (or other shell rc file) to add to your $PATH variable and enable autocompletion. - -See also --initial-setup - - - - ---author - -Display contact information for the -author. - - - - ---color - -Enable colorful output. (This is the default for interactive terminals). - - - - ---generate-vscode-project-config - -Generate a .vscode directory with configurations for building and debugging -in Visual Studio Code. - - - - ---nice=value - -This value adjusts the computer CPU priority requested by , and -should be in the range of 0-20. 0 is highest priority (because it is the -least nice), 20 is lowest priority. defaults -to 10. - - - - ---no-async - -Disables the asynchronous mode of updating. -Instead the update will be performed in its entirety before the build starts. -This option will slow down the overall process, but if you encounter IPC errors -while running try using this option, and submitting a -https://bugs.kde.org/;>bug report. - - - - ---no-color - -Disable colorful output. - - - - ---pretend (or -p) - - will run through the update and build process, but instead of -performing any actions to update or build, will instead output what the -script would have done (e.g. what commands to run, general steps being taken, -etc.). - -Simple read-only commands (such as reading file information) may -still be run to make the output more relevant (such as correctly simulating -whether source code would be checked out or updated). - - -This option requires that some needed metadata is available, -which is normally automatically downloaded, but downloads are disabled in -pretend mode. If you've never run (and therefore, don't have -this metadata), you should run kdesrc-build ---metadata-only to download the required metadata -first. - - - - - ---quiet (or -q) - -Do not be as noisy with the output. With this switch only the basics are -output. - - - - ---really-quiet - -Only output warnings and errors. - - - - ---verbose - -Be very descriptive about what is going on, and what is doing. - - - - ---src-only (or -s) - -Only perform the source update. - - - - ---build-only - -Only perform the build process. - - - - ---install-only - -If this is the only command-line option, it tries to install all of the modules -contained in log/latest/build-status. If command-line -options are specified after --install-only, they are all -assumed to be modules to install (even if they did not successfully build on -the last run). - - - - ---metadata-only - -Only perform the metadata download process. normally handles this -automatically, but you might manually use this to allow the --pretend command line option to work. - - - - ---rebuild-failures - -Use this option to build only those modules which failed to build on a previous - run. This is useful if a significant number of failures occurred mixed with
[sdk/kdesrc-build] doc: doc: kdesrc-build-logging - separate docbook
Git commit 93412946d1e2df4374d280350631da819e5f0caf by Andrew Shark.
Committed on 05/01/2024 at 20:00.
Pushed by ashark into branch 'master'.
doc: kdesrc-build-logging - separate docbook
M +1-78 doc/features.docbook
M +1-0doc/index.docbook
A +78 -0doc/kdesrc-build-logging.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/93412946d1e2df4374d280350631da819e5f0caf
diff --git a/doc/features.docbook b/doc/features.docbook
index 2a911dc3..723cb706 100644
--- a/doc/features.docbook
+++ b/doc/features.docbook
@@ -180,83 +180,6 @@ always point to the most recent log entry in the log
directory.
-
-'s build logging
-
-
-Logging overview
-
-Logging is a feature whereby the output from every command
-that runs is saved to a file for examination later, if
-necessary. This is done because it is often necessary to have the output of
-these programs when there is a build failure, because there are so many
-reasons why a build can fail in the first place.
-
-
-Logging directory layout
-
-The logs are always stored under the log directory. The destination of
-the log directory is controlled by the log-dir
-option, which defaults to ${source-dir}/log (where
-${source-dir} is the value of the source-dir
-option. The in rest of this section, this value will be referred to as
-${log-dir}).
-
-Under ${log-dir}, is a set of directories, one for every
-time that was run. Each directory is named with the date, and
-the run number. For instance, the second time that is run on
-May 26, 2004, it would create a directory called
2004-05-26-02,
-where the 2004-05-26 is for the date, and the -02 is the run number.
-
-For your convenience, will also create a link to the
-logs for your latest run, called latest. So the logs for
-the most recent run should always be under ${log-dir}/latest.
-
-
-Now, each directory for a run will itself contain a set of
-directories, one for every module that tries to build.
Also,
-a file called build-status will be contained in the
directory,
-which will allow you to determine which modules built and which failed.
-
-
-If a module itself has a submodule (such as extragear/multimedia,
-playground/utils, or KDE/kdelibs), then there would actually be a matching
-layout in the log directory. For example, the logs for KDE/kdelibs after the
-last run would be found in ${log-dir}/latest/KDE/kdelibs,
-and not under ${log-dir}/latest/kdelibs.
-
-
-In each module log directory, you will find a set of files for each
-operation that performs. If updates a module,
-you may see filenames such as git-checkout-update.log
(for a
-module checkout or when updating a module
-that has already been checked out). If the configure
-command was run, then you would expect to see a
configure.log
-in that directory.
-
-If an error occurred, you should be able to see an explanation of why in
-one of the files. To help you determine which file contains the error,
- will create a link from the file containing the error (such as
-build-1.log to a file called
error.log).
-
-The upshot to all of this is that to see why a module failed to build
-after your last , the file you should look at first is
-${log-dir}/latest/module-name/error.log.
-
-
-If the file error.log is empty (especially
after
-an installation), then perhaps there was no error. Some of the tools used by
-the build system will sometimes mistakenly report an error when there was
-none.
-
-Also, some commands will evade 's output redirection and
-bypass the log file in certain circumstances (normally when performing the
-first checkout), and the error output in that case is not in the log file
-but is instead at the or terminal where you ran
.
-
-
-
-
-
+
diff --git a/doc/index.docbook b/doc/index.docbook
index b7801670..78e55044 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -85,6 +85,7 @@
+
]>
diff --git a/doc/kdesrc-build-logging.docbook b/doc/kdesrc-build-logging.docbook
new file mode 100644
index ..91f751ac
--- /dev/null
+++ b/doc/kdesrc-build-logging.docbook
@@ -0,0 +1,78 @@
+
+'s build logging
+
+
+Logging overview
+
+Logging is a feature whereby the output from every command
+that runs is saved to a file for examination later, if
+necessary. This is done because it is often necessary to have the output of
+these programs when there is a build failure, because there are so many
+reasons why a build can fail in the first place.
+
+
+Logging directory layout
+
+The logs are always stored under the log directory. The destination of
+the log directory is controlled by the log-dir
+option, which defaults to ${source-dir}/log (where
+${source-dir} is the value of the source-dir
+option. The in rest of this section, this value will be referred to as
+${log-dir}).
+
+Under ${log-dir}, is a set of directories, one for every
+time that was run. Each directory is named with the date, and
+the run number. For instance, the second time that is run on
+May 26, 2004, it would
[sdk/kdesrc-build] doc: doc: kde-modules-and-selection - separate docbook
Git commit 19c4426fa7fdd6218cabbd2dfab0d0c848994fed by Andrew Shark. Committed on 05/01/2024 at 20:00. Pushed by ashark into branch 'master'. doc: kde-modules-and-selection - separate docbook M +1-353 doc/getting-started.docbook M +1-0doc/index.docbook C +0-238 doc/kde-modules-and-selection.docbook [from: doc/getting-started.docbook - 059% similarity] https://invent.kde.org/sdk/kdesrc-build/-/commit/19c4426fa7fdd6218cabbd2dfab0d0c848994fed diff --git a/doc/getting-started.docbook b/doc/getting-started.docbook index 53d0d1b8..98997abf 100644 --- a/doc/getting-started.docbook +++ b/doc/getting-started.docbook @@ -216,359 +216,7 @@ linkend="configure-data" /> and in . - -Module Organization and selection - - -KDE Software Organization - - - software is split into different components, many of which can be built -by . Understanding this organization will help you properly -select the software modules that you want built. - - - -At the lowest level comes the library, which is a -very powerful, cross-platform toolkit library. is based on -, and some of the non- libraries required by are also based on -. can build , or use the one already installed on your -system if it is a recent enough version. - -On top of are required libraries that are necessary for - software to work. Some of these libraries are not considered part of - itself due to their generic nature, but are still essential to the -Platform. These libraries are collected under a kdesupport -module grouping but are not considered part of the Frameworks -libraries. - - -On top of these essential libraries come the https://community.kde.org/Frameworks;> Frameworks, sometimes -abbreviated as KF5, which are essential libraries for the Plasma desktop, - Applications, and other third-party software. - - -On top of the Frameworks, come several different things: - -Third-party applications. These are -applications that use the Frameworks or are designed to run under - Plasma but are not authored by or in association with the -project. - -Plasma, which is a full workspace desktop -environment. This is what users normally see when they log-in to -. - -The Application suite. This is a collection of -useful software included with the Platform and Desktop, grouped into -individual modules, including utilities like , games like -KSudoku, and productivity software released by -such as . - -Finally, there is a collection of software (also -collected in modules) whose development is supported by resources -(such as translation, source control, bug tracking, ) but is not -released by as part of Plasma or the Application suite. These -modules are known as Extragear. - - - - - - - -Selecting modules to build - -Selecting which of the possible modules to build is controlled by -the configuration file. -After the global section is a list of modules to build, -bracketed by module ... end module lines. An example entry for a module is -shown in . - - -Example module entry in the configuration file - -module kdesrc-build-git -# Options for this module go here, example: -repository kde:kdesrc-build -make-options -j4 # Run 4 compiles at a time -end module - - - -In practice, this module construct is not usually used directly. Instead -most modules are specified via module-sets as described below. - -When using only module entries, builds them in the order -you list, and does not attempt to download any other repositories other than what you specify -directly. - - - - - -Module Sets - -The source code is decomposed into a great number of relatively -small Git-based repositories. To make it easier to manage the large number of -repositories involved in any useful -based install, supports -grouping multiple modules and treating the group as a module set. - - - -The basic module set concept - -By using a module set, you can quickly declare many Git modules to be -downloaded and built, as if you'd typed out a separate module declaration for -each one. The repository option is -handled specially to setup where each module is downloaded from, and every -other option contained in the module set is copied to every module generated -in this fashion. - - -Using module sets - -global -git-repository-base kde-git kde: -end global - -module qt -# Options removed for brevity -end module - -module-set kde-support-libs -repository kde-git -use-modules automoc attica akonadi -end module-set - -# Other modules as necessary... -module kdesupport -end module - - - -In a brief module set is -shown. When encounters this module set, it acts as if, for -every module given in use-modules, that an individual module -has been declared, with its repository equal to the -module-set's repository followed immediately by the given -module name. - -In addition, other
[sdk/kdesrc-build] doc: doc: other-features - separate docbook
Git commit 4c8ef70683eb7eaa5890cfa4e7206dc401b42e57 by Andrew Shark. Committed on 05/01/2024 at 20:00. Pushed by ashark into branch 'master'. doc: other-features - separate docbook M +2-142 doc/index.docbook A +142 -0doc/other-features.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/4c8ef70683eb7eaa5890cfa4e7206dc401b42e57 diff --git a/doc/index.docbook b/doc/index.docbook index f8b1b1a7..7592879a 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -87,6 +87,7 @@ + ]> @@ -184,148 +185,7 @@ do with this tool. - -Other features - - -Changing the amount of output from - has several options to control the amount of output the -script generates. In any case, errors will always be output. - - -The --quiet option (short form is --q) causes to be mostly silent. Only important -messages, warnings, or errors will be shown. When available, build progress -information is still shown. - -The --really-quiet option (no short form) -causes to only display important warnings or errors while it is -running. - -The --verbose option (short form is --v) causes to be very detailed in its -output. - -The --debug option is for debugging purposes -only, it causes to act as if --verbose was -turned on, causes commands to also output to the terminal, and will display -debugging information for many functions. - - - - - -Color output -When being run from or a different terminal, -will normally display with colorized text. - -You can disable this by using the --no-color on the -command line, or by setting the option in the configuration file to -false. - - - -Disabling color output in the configuration file: - -global - colorful-output false -end global - - - - - - -Removing unneeded directories after a build -Are you short on disk space but still want to run a bleeding-edge - checkout? can help reduce your disk usage when building - from . - -Be aware that building does take a lot of space. There are -several major space-using pieces when using : - - -The actual source checkout can take up a fair amount of space. -The default modules take up about 1.6 gigabytes of on-disk space. You can reduce -this amount by making sure that you are only building as many modules as you -actually want. will not delete source code from disk even if you -delete the entry from the configuration file, so make sure that you go and delete unused -source checkouts from the source directory. Note that the source files are -downloaded from the Internet, you should not delete them -if you are actually using them, at least until you are done using -. - -Also, if you already have a installed by your distribution (and -the odds are good that you do), you probably do not need to install the -qt module. That will shave about 200 megabytes off of the on-disk source -size. - - - - will create a separate build directory to build the source -code in. Sometimes will have to copy a source directory to -create a fake build directory. When this happens, space-saving symlinks are -used, so this should not be a hassle on disk space. The build directory will -typically be much larger than the source directory for a module. For example, -the build directory for kdebase is about 1050 megabytes, whereas kdebase's -source is only around 550 megabytes. - -Luckily, the build directory is not required after a module has -successfully been built and installed. can automatically -remove the build directory after installing a module, see the examples below -for more information. Note that taking this step will make it impossible -for to perform the time-saving incremental builds. - - - -Finally, there is disk space required for the actual installation of -, which does not run from the build directory. This typically takes less -space than the build directory. It is harder to get exact figures however. - - - -How do you reduce the space requirements of ? One way is to -use the proper compiler flags, to optimize for space reduction instead of -for speed. Another way, which can have a large effect, is to remove debugging -information from your build. - - - -You should be very sure you know what you are doing before deciding to remove -debugging information. Running bleeding-edge software means you are running -software which is potentially much more likely to crash than a stable release. -If you are running software without debugging information, it can be very -hard to create a good bug report to get your bug resolved, and you will likely -have to re-enable debugging information for the affected application and -rebuild to help a developer fix the crash. So, remove debugging information -at your own risk! - - - -Removing the build directory after installation of a module. The source -directory is still kept, and debugging is enabled: - - -global - configure-flags --enable-debug - remove-after-install builddir# Remove build directory after install -end global - - -Removing the build directory
[sdk/kdesrc-build] doc: doc: supported-envvars - separate docbook
Git commit 9a361f06e316d11f3c01e5e9262615d677464863 by Andrew Shark. Committed on 05/01/2024 at 20:00. Pushed by ashark into branch 'master'. doc: supported-envvars - separate docbook M +1-10 doc/cmdline.docbook M +1-0doc/index.docbook A +10 -0doc/supported-envvars.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/9a361f06e316d11f3c01e5e9262615d677464863 diff --git a/doc/cmdline.docbook b/doc/cmdline.docbook index 4273c346..a3380279 100644 --- a/doc/cmdline.docbook +++ b/doc/cmdline.docbook @@ -98,16 +98,7 @@ modules you want. - -Supported Environment Variables - - - does not use environment variables. If you need to set environment -variables for the build or install process, please see the set-env option. - - - + diff --git a/doc/index.docbook b/doc/index.docbook index 953c9979..7c9b7e16 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -90,6 +90,7 @@ + ]> diff --git a/doc/supported-envvars.docbook b/doc/supported-envvars.docbook new file mode 100644 index ..772b325b --- /dev/null +++ b/doc/supported-envvars.docbook @@ -0,0 +1,10 @@ + +Supported Environment Variables + + + does not use environment variables. If you need to set environment +variables for the build or install process, please see the set-env option. + + +
[sdk/kdesrc-build] doc: doc: quick-start-conclusion - separate docbook
Git commit 24aafe7a055fd0afa487cc702fc0547bb63f9d6d by Andrew Shark. Committed on 05/01/2024 at 20:00. Pushed by ashark into branch 'master'. doc: quick-start-conclusion - separate docbook M +1-17 doc/getting-started.docbook M +1-0doc/index.docbook A +17 -0doc/quick-start-conclusion.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/24aafe7a055fd0afa487cc702fc0547bb63f9d6d diff --git a/doc/getting-started.docbook b/doc/getting-started.docbook index 98997abf..657d8b59 100644 --- a/doc/getting-started.docbook +++ b/doc/getting-started.docbook @@ -218,22 +218,6 @@ linkend="configure-data" /> and in . - -Getting Started Conclusion -These are the major features and concepts needed to get started with - - -For additional information, you could keep reading through this -documentation. In particular, the list -of command-line options and the table -of configuration file options are useful references. - -The Community also maintains https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source;>an -online Wiki reference for how to build the source code, which refers to - and includes tips and other guidelines on how to use the -tool. - - + diff --git a/doc/index.docbook b/doc/index.docbook index 7592879a..98fca4d6 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -88,6 +88,7 @@ + ]> diff --git a/doc/quick-start-conclusion.docbook b/doc/quick-start-conclusion.docbook new file mode 100644 index ..d4a42fce --- /dev/null +++ b/doc/quick-start-conclusion.docbook @@ -0,0 +1,17 @@ + +Getting Started Conclusion +These are the major features and concepts needed to get started with + + +For additional information, you could keep reading through this +documentation. In particular, the list +of command-line options and the table +of configuration file options are useful references. + +The Community also maintains https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source;>an +online Wiki reference for how to build the source code, which refers to + and includes tips and other guidelines on how to use the +tool. + +
[sdk/kdesrc-build] doc: doc: kdesrc-buildrc - separate docbook
Git commit 7f814fbe007722d5c63c4b5ad011dbe85ba90765 by Andrew Shark.
Committed on 05/01/2024 at 20:00.
Pushed by ashark into branch 'master'.
doc: kdesrc-buildrc - separate docbook
M +2-231 doc/index.docbook
A +231 -0doc/kdesrc-buildrc.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/7f814fbe007722d5c63c4b5ad011dbe85ba90765
diff --git a/doc/index.docbook b/doc/index.docbook
index 78e55044..f8b1b1a7 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -86,6 +86,7 @@
+
]>
@@ -152,237 +153,7 @@ directly from the project's source code
repositories.
-
-Configuring
-
-
-Overview of configuration
-
-
-To use the script, you must have a file in your home directory called
-.kdesrc-buildrc, which describes the modules you would
-like to download and build, and any options or configuration parameters to
-use for these modules.
-
-
-
-Layout of the configuration file
-
-
-Global configuration
-
-
-The configuration file starts with the global options, specified like the
-following:
-
-
-
-global
-option-name option-value
-[...]
-end global
-
-
-
-
-Module configuration
-
-
-It is then followed by one or more module sections, specified in one of the
-following two forms:
-
-
-
-
-
-module module-name
-option-name option-value
-[...]
-end module
-
-
-
-
-
-module-set module-set-name
- repository kde-projects or
git://host.org/path/to/repo.git
- use-modules module-names
-
-# Other options may also be set
-option-name option-value
-[...]
-end module-set
-
-
-
-
-Note that the second form, module sets, only works
-for Git-based modules.
-
-
-For Git modules, module-name must be a module
-from the repository (for example, kdeartwork or
-kde-wallpapers).
-
-
-
-For Git modules, the module name can be essentially whatever you'd like, as
-long as it does not duplicate any other module name in the configuration. Keep
-in mind the source and build directory layout will be based on the module name
-if you do not use the dest-dir option.
-
-
-However, for Git module sets the
-module-names must correspond with actual git modules
-in the chosen repository. See git-repository-base or use-modules for more information.
-
-
-
-
-
-Processing of option values
-
-In general, the entire line contents after the
-option-name is used as the
-option-value.
-
-One modification that performs is that a sequence
-${name-of-option} is replaced
-with the value of that option from the global configuration. This allows you
-to reference the value of existing options, including options already set by
-.
-
-
-To see an example of this in use, see
-.
-
-
-
-
-options modules
-
-There is a final type of configuration file entry,
-options groups, which may be given wherever a
-module or module-set may be used.
-
-
-options module-name
-option-name option-value
-[...]
-end options
-
-
-An options group may have options set for it just like
-a module declaration, and is associated with an existing module. Any options
-set these way will be used to override options set for the
-associated module.
-
-The associated module name must match the
-name given in the options declaration. Be careful of
-mis-typing the name.
-
-This is useful to allow for declaring an entire
-module-set worth of modules, all using the same options, and
-then using options groups to make individual changes.
-
-options groups can also apply to named module sets.
-This allows expert users to use a common configuration file (which includes
-module-set declarations) as a baseline, and then make
changes
-to the options used by those module-sets in configuration files that
-use the include command to
reference
-the base configuration.
-
-
-Example of using options
-
-In this example we choose to build all modules from the multimedia
-software grouping. However we want to use a different version of the
-application (perhaps for testing a bug fix). It works as follows:
-
-
-module-set kde-multimedia-set
- repository kde-projects
- use-modules kde/kdemultimedia
- branch master
-end module-set
-
-# kmix is a part of kde/kdemultimedia group, even though we never named
-# kmix earlier in this file, will figure out the change.
-options kmix
- branch KDE/4.12
-end options
-
-
-Now when you run , all of the multimedia programs
will
-be built from the master branch of the source repository, but
- will be built from the older KDE/4.12 branch. By using
-options you didn't have to individually list all the
-other multimedia programs to give them the right
-branch option.
-
-
-
-
-Note that this feature is only available in from version
-1.16, or using the development version of after
-2014-01-12.
-
-
-
-
-
-
-Including other configuration files
-
-
-Within the configuration file, you may reference other files by using the
-include keyword with a file, which will act as if the file
-referenced had been inserted into the configuration file at that point.
-
-
-For example, you could have something like this:
-
-global
-include
[sdk/kdesrc-build] doc: doc: environment - separate docbook
Git commit 4e14ba8ba891a65db5f7c241b96d8f30129e5b46 by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'. doc: environment - separate docbook A +127 -0doc/environment.docbook M +2-127 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/4e14ba8ba891a65db5f7c241b96d8f30129e5b46 diff --git a/doc/environment.docbook b/doc/environment.docbook new file mode 100644 index ..d5929b59 --- /dev/null +++ b/doc/environment.docbook @@ -0,0 +1,127 @@ + +Setting the Environment to Run Your Desktop + + +Assuming you are using a dedicated user to build , and you already have an +installed version, running your new may be a bit tricky, as the new + has to take precedence over the old. You must change the environment +variables of your login scripts to make sure the newly-built desktop is used. + + + +Automatically installing a login driver + +Starting from version 1.16, will try to install an +appropriate login driver, that will allow you to login to your +-built desktop from your login manager. This can be +disabled by using the install-session-driver +configuration file option. + +Session setup does not occur while is running +in pretend mode. + +This driver works by setting up a custom xsession +session type. This type of session should work by default with the sddm login +manager (where it appears as a Custom session), but other login +managers (such as LightDM and +gdm) may require additional files installed to +enable xsession support. + + +Adding xsession support for distributions + +The default login managers for some distributions may require additional +packages to be installed in order to support xsession logins. + + +The https://getfedora.org/;>Fedora + distribution requires the xorg-x11-xinit-session +package to be installed for custom xsession login +support. + +https://www.debian.org/;>Debian and +Debian-derived distributions should support custom +xsession logins, but require the +allow-user-xsession option to be set in +/etc/X11/Xsession.options. See also the Debian https://www.debian.org/doc/manuals/debian-reference/ch07.en.html#_customizing_the_x_session_classic_method;>documentation +on customizing the X session. + +For other distributions, go to . + + + + + +Manually adding support for xsession + +If there were no distribution-specific directions for your distribution +in , you can manually add a +Custom xsession login entry to your distribution's list of +session types as follows: + + +Adding an .xsession login session type. + +This procedure will likely require administrative privileges to +complete. + + + +Create the file +/usr/share/xsessions/kdesrc-build.desktop. + + + +Ensure the file just created has the following text: + +Type=XSession +Exec=$HOME/.xsession +Name=KDE Plasma Desktop (unstable; kdesrc-build) + + + + +The $HOME entry must be replaced by the full path to +your home directory (example, /home/user). The +desktop entry specification does not allow for user-generic files. + + + + + +When the login manager is restarted, it +should show a new session type, KDE Plasma Desktop (unstable; +kdesrc-build) in its list of sessions, which should try to run the +.xsession file installed by if it is +selected when you login. + +It may be easiest to restart the computer to restart the login +manager, if the login manager does not track updates to the /usr/share/xsessions directory. + + + + + + + + + + +Setting up the environment manually +This documentation used to include instruction on which environment +variables to set in order to load up the newly-built desktop. These +instructions have been moved to an appendix (). + +If you intend to setup your own login support you can consult that +appendix or view the kde-env-master.sh.in file +included with the source. + + + + diff --git a/doc/index.docbook b/doc/index.docbook index 2e8306bb..e4f365d5 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -78,6 +78,7 @@ + ]> @@ -443,133 +444,7 @@ linkend="configure-data" /> and in . - -Setting the Environment to Run Your Desktop - - -Assuming you are using a dedicated user to build , and you already have an -installed version, running your new may be a bit tricky, as the new - has to take precedence over the old. You must change the environment -variables of your login scripts to make sure the newly-built desktop is used. - - - -Automatically installing a login driver - -Starting from version 1.16, will try to install an -appropriate login driver, that will allow you to login to your --built desktop from your login manager. This can be -disabled by using the install-session-driver -configuration file option. - -Session setup does not occur while is running -in pretend mode. - -This driver works by setting up a custom xsession -session type. This type of session should work by default with the sddm login -manager (where it appears as a Custom session), but other login -managers
[sdk/kdesrc-build] doc: doc: getting-started - separate docbook
Git commit 5cffc45604ee1d07cc545220a99ab5443513f196 by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'. doc: getting-started - separate docbook C +0-676 doc/getting-started.docbook [from: doc/index.docbook - 051% similarity] M +2-591 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/5cffc45604ee1d07cc545220a99ab5443513f196 diff --git a/doc/index.docbook b/doc/getting-started.docbook similarity index 51% copy from doc/index.docbook copy to doc/getting-started.docbook index 02ceb3ba..53d0d1b8 100644 --- a/doc/index.docbook +++ b/doc/getting-started.docbook @@ -1,234 +1,3 @@ - - - -Copyright (c) 2005 Carlos Leonhard Woelz -Copyright (c) 2009 Burkhard Lück -Copyright (c) 2007, 2011 Federico Zenith -Copyright (c) 2009-2011 Yuri Chornoivan -... and possibly others. Check the git source repository for specifics. - -Permission is granted to copy, distribute and/or modify this document under -the terms of the GNU Free Documentation License, Version 1.2 or any later -version published by the Free Software Foundation; with no Invariant -Sections, no Front-Cover Texts, and no Back-Cover Texts. - -A copy of the license is included in COPYING.DOC. The license will be -included in the generated documentation as well. - --> - - - - - kdesrc-build"> - BSD'> - Git'> - CMake'> - Make'> - Ninja'> - SSH'> - Cron'> - Sudo'> - URL'> - - - - configure-flags'> - install-dir'> - qtdir'> - build-dir'> - source-dir'> - colorful-output'> - tag'> - branch'> - do-not-compile'> - repository'> - make-install-prefix'> - niceness'> - set-env'> - libname'> - libpath'> - binpath'> - - - --nice'> - --ignore-modules'> - --resume-from'> - --resume-after'> - --reconfigure'> - --refresh-build'> - - - - - - - - - - - - - - - -]> - - - - - Script Manual - - - - - CarlosWoelz -carloswo...@imap-mail.com - - - - - - - -2006 -2007 -2008 -2009 -2010 -2011 -2012 -2013 -2014 -2015 -2016 -2017 -2018 -2019 -Michael Pyne - - - -2005 -Carlos Woelz - - - - -2018-01-20 - 17.12 - - - is a script which builds and installs software -directly from the project's source code repositories. - - - -KDE -kdesdk -git -KDE development - - - - - -Introduction - - -A brief introduction to - - -What is ? - - - is a script to help the community install https://www.kde.org/;> software from its https://git-scm.com/;> source repositories, -and continue to update that software afterwards. -It is particularly intended to support those who need to supporting testing and -development of software, including users testing bugfixes and developers -working on new features. - - -The script can be configured to maintain a single individual -module, a full desktop with application set, or somewhere in between. - - -To get started, see , or continue reading for more -detail on how works and what is covered in this documentation. - - - - - operation in a nutshell - - works by using the tools available to the user at the -command-line, using the same interfaces available to the user. When - is run, the following sequence is followed: - - - reads in the command -line and configuration file, to -determine what to build, compile options to use, where to install, - - - performs a source update for each module. The update continues until all modules -have been updated. Modules that fail to update normally do not stop the build - you will be notified at the end which modules did not -update. - -Modules that were successfully updated are built, have their -test suite run, and are then installed. To reduce the overall time spent, - will by default start building the code as soon as the first -module has completed updating, and allow the remaining updates to continue -behind the scenes. - - - -A very good overview of how modules are -built, including informative diagrams, is provided on https://www.davidrevoy.com/article193/guide-building-krita-on-linux-for- -cats">an online article discussing 's application. This -workflow is what automates for all modules. - - - - - - -Documentation Overview - - -This guide is an overview to describe the following aspects of -operation: - - - -An overview of the steps -required to get started. -Notable features. -The configuration file syntax -and options. -The command line options. - - -Also documented are the steps which you should perform using -other tools ( steps that are not automatically performed by ). - - - - - Getting Started @@ -820,448 +589,3 @@ tool. - - - - -Configuring - - -Overview of configuration - - -To use the script, you must have a file in your home directory called -.kdesrc-buildrc, which describes the modules you would -like to download and build, and any options or configuration parameters to -use for these modules. - - - -Layout of the configuration file - - -Global configuration - -
[sdk/kdesrc-build] doc: doc: using-kdesrc-build - separate docbook
Git commit 0d1b9be51cbdf2d841c95dadb1d31435b7eb0bc2 by Andrew Shark. Committed on 05/01/2024 at 20:00. Pushed by ashark into branch 'master'. doc: using-kdesrc-build - separate docbook M +2-30 doc/index.docbook A +30 -0doc/using-kdesrc-build.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/0d1b9be51cbdf2d841c95dadb1d31435b7eb0bc2 diff --git a/doc/index.docbook b/doc/index.docbook index 7c9b7e16..cd6ecdb9 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -91,6 +91,7 @@ + ]> @@ -161,36 +162,7 @@ directly from the project's source code repositories. - -Using - - -Preface - -Normally using after you have gone through -is as easy as doing the following from a terminal prompt: - - - kdesrc-build - - - will then download the sources for , try to configure -and build them, and then install them. - -Read on to discover how does this, and what else you can -do with this tool. - - - - - - - - - - - - + diff --git a/doc/using-kdesrc-build.docbook b/doc/using-kdesrc-build.docbook new file mode 100644 index ..5c3fabd2 --- /dev/null +++ b/doc/using-kdesrc-build.docbook @@ -0,0 +1,30 @@ + +Using + + +Preface + +Normally using after you have gone through +is as easy as doing the following from a terminal prompt: + + + kdesrc-build + + + will then download the sources for , try to configure +and build them, and then install them. + +Read on to discover how does this, and what else you can +do with this tool. + + + + + + + + + + + +
[sdk/kdesrc-build] doc: doc: conf-options-table - separate docbook
Git commit cce1c6a1d1d4332e84a6e2c681893e274f203a0d by Andrew Shark. Committed on 05/01/2024 at 19:58. Pushed by ashark into branch 'master'. doc: conf-options-table - separate docbook A +1363 -0doc/conf-options-table.docbook [INFRASTRUCTURE] M +2-1363 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/cce1c6a1d1d4332e84a6e2c681893e274f203a0d diff --git a/doc/conf-options-table.docbook b/doc/conf-options-table.docbook new file mode 100644 index ..8c1a32e9 --- /dev/null +++ b/doc/conf-options-table.docbook @@ -0,0 +1,1363 @@ + +Table of available configuration options + +Here is a table of the various options, containing the following +information: + + + +The option name + +A description of how responds if the option is +set in both the global section, and the module section of the configuration file while building a +module. + +Special comments on the purpose and usage of the +option. + + + + +Global scope only options + + + + +Option name +Description + + + + + +async + + +TypeBoolean +Default valueTrue +Available since1.6 + +This option enables the asynchronous mode of operation, where the source +code update and the build process will be performed in parallel, instead of waiting for +all of the source code updates before starting the build process. + + + +colorful-output + +TypeBoolean +Default valueTrue +Set this option to false to disable the colorful output of . +Note that will not output the +color codes to anything but a terminal (such as xterm, , or the normal + console). + + + + +disable-agent-check + + +TypeBoolean +Default valueFalse + +If you are using to download the sources +(such as if you are using the git+ssh protocol), this option controls if will try and +make sure that if you are using ssh-agent, it is actually managing some +identities. This is to try and prevent from asking for your pass phrase +for every module. + + + + +git-desired-protocol + + +TypeString +Default valuegit +History informationThis option was added in 1.16. Prior to 20.06 this option +was used to configure the fetch URL instead of the push URL. As of 20.06 +https is always used when updating KDE projects. + +This option only applies to modules from a project repository. + +What this option actually does is configure which network protocol to +prefer when pushing source code for these modules. Normally the very-efficient +git protocol is used, but this may be blocked in some +networks (e.g. corporate intranets, public Wi-Fi). An alternative protocol +which is much better supported is the https protocol used for +Internet web sites. + +If you are using one of these constrained networks you can set this +option to http to prefer https +communications instead. + +You may also need the http-proxy option if an HTTP proxy is also +needed for network traffic. + +In any other situation you should not set this option as the default +protocol is most efficient. + + + + + +install-environment-driver + + +TypeBoolean +Default valueTrue +Available since17.08 + +Install a shell script that can be +sourced in a user's profile setup scripts to easily establish needed environment +variables to run the Plasma desktop built by . + +This driver will alter the following files: + + +$XDG_CONFIG_HOME/kde-env-master.sh (normally found at ~/.config/kde-env-master.sh). +$XDG_CONFIG_HOME/kde-env-user.sh (normally found at ~/.config/kde-env-user.sh). + + +The kde-env-user.sh is optional. It is +intended for user customizations (see the https://userbase.kde.org/KDE_System_Administration/Environment_Variables#Troubleshooting_and_Debugging;>Troubleshooting and Debugging +section of the UserBase for examples of customizable settings), but these settings +can be set elsewhere by the user in their existing profile setup scripts. + +You can disable this feature by setting this option to +false, and ensuring that the install-session-driver option is +also disabled. + + will not overwrite your existing files (if present) +unless you also pass the --delete-my-settings +command-line option. + + + + +install-session-driver + + +TypeBoolean +Default valueTrue +Available since1.16 + +If enabled, will try to install a driver for the graphical +login manager that allows you to login to your -built desktop. + +This driver will alter the following files: + + +~/.xsession +$XDG_CONFIG_HOME/kde-env-master.sh (normally found at ~/.config/kde-env-master.sh). +$XDG_CONFIG_HOME/kde-env-user.sh (normally found at ~/.config/kde-env-user.sh). + + +If you maintain your own login driver then you can disable this feature by setting this +option to false. If enabled, this feature also enables the +install-environment-driver feature. + + will not overwrite your existing files (if present) +unless you also pass the --delete-my-settings +command-line option. + + + + +niceness + + +TypeInteger +Default value10 + +Set this option to a number between 20 and 0. The higher the number, the +lower a priority
[sdk/kdesrc-build] doc: doc: kde-cmake - separate docbook
Git commit 3e5fffc88db32f4fe3d0fb7f2f9e364f03ab0d91 by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'. doc: kde-cmake - separate docbook M +2-29 doc/index.docbook A +29 -0doc/kde-cmake.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/3e5fffc88db32f4fe3d0fb7f2f9e364f03ab0d91 diff --git a/doc/index.docbook b/doc/index.docbook index 39d821d5..d17b5b80 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -83,6 +83,7 @@ + ]> @@ -555,35 +556,7 @@ end global - -, the build system - - -Introduction to - -In March 2006, the program -beat out several competitors and was selected to be the build system for 4, replacing the -autotools-based system that had used from the beginning. - -A introduction to page is available on the https://community.kde.org/Guidelines_HOWTOs/CMake;> Community Wiki. -Basically, instead of running make -f -Makefile.cvs, then configure, -then , we simply run and then . - - - has support for . A few features of -were really features of the underlying buildsystem, including -configure-flags -and do-not-compile. When equivalent -features are available, they are provided. For instance, the equivalent to the -configure-flags option is cmake-options, and the -do-not-compile option is also supported for -as of version 1.6.3. - - - - + diff --git a/doc/kde-cmake.docbook b/doc/kde-cmake.docbook new file mode 100644 index ..9c818591 --- /dev/null +++ b/doc/kde-cmake.docbook @@ -0,0 +1,29 @@ + +, the build system + + +Introduction to + +In March 2006, the program +beat out several competitors and was selected to be the build system for 4, replacing the +autotools-based system that had used from the beginning. + +A introduction to page is available on the https://community.kde.org/Guidelines_HOWTOs/CMake;> Community Wiki. +Basically, instead of running make -f +Makefile.cvs, then configure, +then , we simply run and then . + + + has support for . A few features of +were really features of the underlying buildsystem, including +configure-flags +and do-not-compile. When equivalent +features are available, they are provided. For instance, the equivalent to the +configure-flags option is cmake-options, and the +do-not-compile option is also supported for +as of version 1.6.3. + + + +
[sdk/kdesrc-build] doc: doc: features - separate docbook
Git commit 17357b81a15786f0066759f9433819912678f87b by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'. doc: features - separate docbook A +262 -0doc/features.docbook M +2-262 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/17357b81a15786f0066759f9433819912678f87b diff --git a/doc/features.docbook b/doc/features.docbook new file mode 100644 index ..2a911dc3 --- /dev/null +++ b/doc/features.docbook @@ -0,0 +1,262 @@ + +Script Features + + +Feature Overview + + + features include: + + + + + +You can pretend to do the operations. If you pass +--pretend or -p on the +command line, the script will give a verbose description of the commands +it is about to execute, without actually executing it. However if you've never +run , you would want to run the kdesrc-build +--metadata-only +command first in order for --pretend to work. + +For an even more verbose description of what is +doing, try using the --debug option. + + + + + + allows you to checkout modules quickly. If the module you are checking out +has already been checked out previously, then will download only commits +that are not yet on your computer. + + +There is generally no need for any special preparation to perform +the initial checkout of a Git module, as the entire Git repository must be +downloaded anyways, so it is easy for the server to determine what to +send. + +This is faster for you, and helps to ease the load on the kde.org +anonymous servers. + + + +Another speedup is provided by starting the build process for a module as soon +as the source code for that module has been downloaded. (Available since +version 1.6) + + + +Excellent support for building the library (in case the software you +are trying to build depends on a recent not available in your +distribution). + + + + does not require a GUI present to operate. So, +you can build software without needing a graphical environment. + + + +Supports setting default options for all modules (such as the compilation +settings or the configuration options). Such options can normally be changed +for specific modules as well. + +Also, will add +standard flags as appropriate to save you the trouble and possible +errors from typing them yourself. Nota Bene: this does not apply when a (custom) +toolchain is configured through e.g.: +cmake-toolchain + + + + can checkout a specific branch +or tag of a module. You can also ensure that a specific revision is checked out of a module. + + + + can automatically switch a source directory to checkout from +a different repository, branch, or tag. This happens automatically when you +change an option that changes what the repository should be, but you must +use the --src-only option to let + know that it is acceptable to perform the switch. + + + + can checkout only portions of a +module, for those situations where you only need one program from a +large module. + + + +For developers: will remind +you if you use git+ssh:// but ssh-agent is +not running, as this will lead to repeated password requests from +. + + + +Can delete the build directory of a +module after its installation to save space at the expense of future compilation +time. + + + +The locations for the directories used by are configurable (even +per module). + + + +Can use , or a different user-specified command +to install modules so that + does not need to be run as the super user. + + + + runs with reduced priority +by default to allow you to still use your computer while is +working. + + + +Has support for using 's tags and +branches. + + + +There is support for resuming a build from a +given module. You can even ignore some +modules temporarily for a given build. + + + + will show the progress of your +build when using , and will always time the build +process so you know after the fact how long it took. + + + +Comes built-in with a sane set of default options appropriate for building +a base single-user installation from the anonymous source repositories. + + + +Tilde-expansion for your configuration options. For example, you can +specify: +qtdir ~/kdesrc/build/qt + + + +Automatically sets up a build system, with the source directory not the +same as the build directory, in order to keep the source directory +pristine. + + + +You can specify global options to apply to every module to check out, and +you can specify options to apply to individual modules as well. + + + +Forced full rebuilds, by running + with the --refresh-build option. + + + +You can specify various environment values to be used during the build, +including QTDIR, DO_NOT_COMPILE, +and CXXFLAGS. + + + +Command logging. Logs are dated and numbered so that you always have a +log of a script run. Also, a special symlink called latest is created to +always point to the most recent log entry in the log directory. + + + + + + + +'s build logging + + +Logging overview + +Logging is a feature whereby the output from every command
[sdk/kdesrc-build] doc: doc: introduction - separate docbook
Git commit 894df557e1279b21d7f5249f12c76d33885bf4ad by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'. doc: introduction - separate docbook M +2-67 doc/index.docbook A +67 -0doc/introduction.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/894df557e1279b21d7f5249f12c76d33885bf4ad diff --git a/doc/index.docbook b/doc/index.docbook index 3038d2d2..39d821d5 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -82,6 +82,7 @@ + ]> @@ -142,73 +143,7 @@ directly from the project's source code repositories. - -Introduction - - -A brief introduction to - - -What is ? - - - is a script to help the community install https://www.kde.org/;> software from its https://git-scm.com/;> source repositories, -and continue to update that software afterwards. -It is particularly intended to support those who need to supporting testing and -development of software, including users testing bugfixes and developers -working on new features. - - -The script can be configured to maintain a single individual -module, a full desktop with application set, or somewhere in between. - - -To get started, see , or continue reading for more -detail on how works and what is covered in this documentation. - - - - - operation in a nutshell - - works by using the tools available to the user at the -command-line, using the same interfaces available to the user. When - is run, the following sequence is followed: - - - reads in the command -line and configuration file, to -determine what to build, compile options to use, where to install, - - - performs a source update for each module. The update continues until all modules -have been updated. Modules that fail to update normally do not stop the build - you will be notified at the end which modules did not -update. - -Modules that were successfully updated are built, have their -test suite run, and are then installed. To reduce the overall time spent, - will by default start building the code as soon as the first -module has completed updating, and allow the remaining updates to continue -behind the scenes. - - - -A very good overview of how modules are -built, including informative diagrams, is provided on https://www.davidrevoy.com/article193/guide-building-krita-on-linux-for- -cats">an online article discussing 's application. This -workflow is what automates for all modules. - - - - - - - + diff --git a/doc/introduction.docbook b/doc/introduction.docbook new file mode 100644 index ..e6ca3256 --- /dev/null +++ b/doc/introduction.docbook @@ -0,0 +1,67 @@ + +Introduction + + +A brief introduction to + + +What is ? + + + is a script to help the community install https://www.kde.org/;> software from its https://git-scm.com/;> source repositories, +and continue to update that software afterwards. +It is particularly intended to support those who need to supporting testing and +development of software, including users testing bugfixes and developers +working on new features. + + +The script can be configured to maintain a single individual +module, a full desktop with application set, or somewhere in between. + + +To get started, see , or continue reading for more +detail on how works and what is covered in this documentation. + + + + + operation in a nutshell + + works by using the tools available to the user at the +command-line, using the same interfaces available to the user. When + is run, the following sequence is followed: + + + reads in the command +line and configuration file, to +determine what to build, compile options to use, where to install, + + + performs a source update for each module. The update continues until all modules +have been updated. Modules that fail to update normally do not stop the build + you will be notified at the end which modules did not +update. + +Modules that were successfully updated are built, have their +test suite run, and are then installed. To reduce the overall time spent, + will by default start building the code as soon as the first +module has completed updating, and allow the remaining updates to continue +behind the scenes. + + + +A very good overview of how modules are +built, including informative diagrams, is provided on https://www.davidrevoy.com/article193/guide-building-krita-on-linux-for- +cats">an online article discussing 's application. This +workflow is what automates for all modules. + + + + + + +
[sdk/kdesrc-build] doc: doc: cmdline - separate docbook
Git commit 6496ae8eabf61c86d586f11a0c4000bf9fb9076b by Andrew Shark. Committed on 05/01/2024 at 19:58. Pushed by ashark into branch 'master'. doc: cmdline - separate docbook A +837 -0doc/cmdline.docbook M +2-837 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/6496ae8eabf61c86d586f11a0c4000bf9fb9076b diff --git a/doc/cmdline.docbook b/doc/cmdline.docbook new file mode 100644 index ..ecec619f --- /dev/null +++ b/doc/cmdline.docbook @@ -0,0 +1,837 @@ + +Command Line Options and Environment Variables + + +Command Line Usage + + is designed to be run as follows: + + +kdesrc-build +--options +modules to build + + +If no modules to build are specified on the command line, then +kdesrc-build will build all modules defined in its configuration file, in the +order listed in that file (although this can be modified by various +configuration file options). + + +Commonly used command line options + +The full list of command line options is given in . The most-commonly used options +include: + + + +--pretend (or -p) +This option causes to indicate what actions +it would take, without actually really implementing them. This can be +useful to make sure that the modules you think you are building will +actually get built. + + + +--refresh-build +This option forces to build the given +modules from an absolutely fresh start point. Any existing build directory +for that module is removed and it is rebuilt. This option is useful if you +have errors building a module, and sometimes is required when or +libraries change. + + + +--no-src +This option skips the source update process. You might use +it if you have very recently updated the source code (perhaps you did it +manually or recently ran ) but still want to rebuild some +modules. + + + +--no-build +This option is similar to --no-src above, +but this time the build process is skipped. + + + + + + +Specifying modules to build + +In general, specifying modules to build is as simple as passing their +module name as you defined it in the configuration file. You can also pass +modules that are part of a module set, either as named on use-modules, or the name of the entire module +set itself, if you have given it a name. + +In the specific case of module sets based against the KDE project database, +will expand module name components to determine the exact module you +want. For example, 's KDE project entry locates the project in +extragear/utils/kdesrc-build. You could specify any +of the following to build : + + + + kdesrc-build +extragear/utils/kdesrc-build + kdesrc-build +utils/kdesrc-build + kdesrc-build +kdesrc-build + + + +The commands in the previous example preceded the module-name with +a +. This forces the module name to be interpreted as a module +from the KDE project database, even if that module hasn't been defined in your +configuration file. + + +Be careful about specifying very generic projects (e.g. +extragear/utils by itself), as this can lead to a large +amount of modules being built. You should use the --pretend +option before building a new module set to ensure it is only building the +modules you want. + + + + + +Supported Environment Variables + + + does not use environment variables. If you need to set environment +variables for the build or install process, please see the set-env option. + + + + + +Supported command-line parameters + + +The script accepts the following command-line options: + + + + + +--async + +Enables the asynchronous mode, which can +perform the source code updates and module builds at the same time. This is +the default, this option only needs specified if you have disabled it in the +configuration. + + + + +--help (or -h) + +Only display simple help on this script. + + + + +--version (or -v) + +Display the program version. + + + + +--show-info + +Displays information about and the operating system, that may +prove useful in bug reports or when asking for help in forums or mailing lists. + +Available since version 18.11. + + + + +--initial-setup + +Has perform the one-time initial setup necessary to prepare +the system for to operate, and for the newly-installed +software to run. + +This includes: + +Installing known dependencies (on supported distributions) +Adding required environment variables to ~/.bashrc +Setting up a configuration file + +This option is exactly equivalent to using +--install-distro-packages +--generate-config +--update-shellrc at the same time. + + + + + +--install-distro-packages + +Installs distro packages (on supported distributions) necessary to prepare the system for to operate, and for the newly-installed +software to run. + +See also --initial-setup + + + + +--generate-config + +Generate the configuration file. + +See also --initial-setup + + + + +--update-shellrc + +Edit the "~/.bashrc" (or other shell rc file) to add to your $PATH
[sdk/kdesrc-build] doc: doc: intro-toc - separate docbook
Git commit fae18088f19548e12d9aef2c24321bb8f6bc9c5f by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'. doc: intro-toc - separate docbook M +2-22 doc/index.docbook A +22 -0doc/intro-toc.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/fae18088f19548e12d9aef2c24321bb8f6bc9c5f diff --git a/doc/index.docbook b/doc/index.docbook index d506542a..3038d2d2 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -81,6 +81,7 @@ + ]> @@ -206,28 +207,7 @@ workflow is what automates for all modules. - -Documentation Overview - - -This guide is an overview to describe the following aspects of -operation: - - - -An overview of the steps -required to get started. -Notable features. -The configuration file syntax -and options. -The command line options. - - -Also documented are the steps which you should perform using -other tools ( steps that are not automatically performed by ). - - - + diff --git a/doc/intro-toc.docbook b/doc/intro-toc.docbook new file mode 100644 index ..00b36bf6 --- /dev/null +++ b/doc/intro-toc.docbook @@ -0,0 +1,22 @@ + +Documentation Overview + + +This guide is an overview to describe the following aspects of +operation: + + + +An overview of the steps +required to get started. +Notable features. +The configuration file syntax +and options. +The command line options. + + +Also documented are the steps which you should perform using +other tools ( steps that are not automatically performed by ). + + +
[sdk/kdesrc-build] doc: doc: configure-data - separate docbook
Git commit bdd65e23ec996e9b2d286d556de32890e70833e6 by Andrew Shark.
Committed on 05/01/2024 at 19:58.
Pushed by ashark into branch 'master'.
doc: configure-data - separate docbook
A +110 -0doc/configure-data.docbook
M +2-110 doc/index.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/bdd65e23ec996e9b2d286d556de32890e70833e6
diff --git a/doc/configure-data.docbook b/doc/configure-data.docbook
new file mode 100644
index ..a4019619
--- /dev/null
+++ b/doc/configure-data.docbook
@@ -0,0 +1,110 @@
+
+Setting the Configuration Data
+
+
+To use , you should have a file in your
~/.config
+(or in $XDG_CONFIG_HOME, if set) directory called
+kdesrc-buildrc, which sets the general options and
+specifies the modules you would like to download and build.
+
+
+
+It is possible to use different configuration files for , which
is
+described in . If you need to use multiple
+configurations, please see that section. Here, we will assume that the
+configuration is stored in ~/.config/kdesrc-buildrc.
+
+
+
+The easiest way to proceed is to use the
+kdesrc-buildrc-kf5-sample file as a template, changing
global
+options to match your wants, and also change the list of modules you want to
+build.
+
+
+
+The default settings should be appropriate to perform a
+ build. Some settings that you may wish to alter include:
+
+
+
+install-dir, which
changes the
+destination directory that your software is installed to. This defaults
to
+~/kde/usr, which is a single-user
+installation.
+
+branch-group, which
can
+be
+used to choose the appropriate branch of development for the modules as a
+whole. There are many supported build configurations but you will likely want
to
+choose kf5-qt5 so that downloads the latest
code
+based on 5 and Frameworks 5.
+
+ will use a default branch group if you do not choose
+one, but this default will change over time, so it's better to choose one so
+that the branch group does not change unexpectedly.
+
+
+source-dir, to control
the directory
+ uses for downloading the source code, running the build
process, and saving
+logs.
+This defaults to ~/kde/src.
+
+cmake-options, which
+sets the options to pass to the command when building each module.
+Typically this is used to set between debug or
+release builds, to enable (or disable) optional features, or to
+pass information to the build process about the location of required libraries.
+
+
+make-options, which
+sets the options used when actually running the make
+command to build each module (once has established the build system).
+
+
+The most typical option is
-jN,
+where N should be replaced with the maximum number
of
+compile jobs you wish to allow. A higher number (up to the number of logical
CPUs
+your system has available) leads to quicker builds, but requires more system
resources.
+
+
+ sets the option num-cores to
+the detected number of available processing cores. You can use this value
+in your own configuration file to avoid having to set it manually.
+
+
+
+Configuring Make to use all available CPUs, with exceptions
+
+global
+# This environment variable is automatically used by make, including
+# make commands not run by kdesrc-build directly, such as Qt's configure
+set-env MAKEFLAGS -j${num-cores}
+
+end global
+
+
+
+module-set big-module-set
+repository kde-projects
+use-modules calligra
+make-options -j2 # Reduced number of build jobs for just these modules
+end module-set
+
+
+
+Some very large Git repositories may swamp your system if you try
to
+compile with a too many build jobs at one time, especially repositories like
the
+ WebKit and WebEngine repositories. To maintain system interactivity
+you may have to reduce the number of build jobs for specific modules.
+ gives an example of how to do
+this.
+
+
+
+
+
+You may want to select different modules to build,
+which is described in .
+
+
diff --git a/doc/index.docbook b/doc/index.docbook
index 2df7f7b9..12020c0d 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -75,6 +75,7 @@
+
]>
@@ -434,116 +435,7 @@ linkend="configure-data" /> and in .
-
-Setting the Configuration Data
-
-
-To use , you should have a file in your
~/.config
-(or in $XDG_CONFIG_HOME, if set) directory called
-kdesrc-buildrc, which sets the general options and
-specifies the modules you would like to download and build.
-
-
-
-It is possible to use different configuration files for , which
is
-described in . If you need to use multiple
-configurations, please see that section. Here, we will assume that the
-configuration is stored in ~/.config/kdesrc-buildrc.
-
-
-
-The easiest way to proceed is to use the
-kdesrc-buildrc-kf5-sample file as a template, changing
global
-options to match your wants, and also change the list of modules you want to
-build.
-
-
-
-The default settings should be appropriate to perform a
- build. Some settings that you may wish to alter include:
-
-
-
-install-dir,
[sdk/kdesrc-build] doc: doc: developer-features - separate docbook
Git commit edc4c2b17ec35a321a6460189a01e6ed869c64e6 by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'. doc: developer-features - separate docbook A +33 -0doc/developer-features.docbook M +2-33 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/edc4c2b17ec35a321a6460189a01e6ed869c64e6 diff --git a/doc/developer-features.docbook b/doc/developer-features.docbook new file mode 100644 index ..1a5dc69a --- /dev/null +++ b/doc/developer-features.docbook @@ -0,0 +1,33 @@ + +Features for developers + + + Agent checks + can ensure that developers that use to +access the source repository do not accidentally forget to leave the + Agent tool enabled. This can cause to hang indefinitely +waiting for the developer to type in their password, +so by default will check if the Agent is running before +performing source updates. + + +This is only done for developers using . + + +You may wish to disable the Agent check, in case of situations where + is mis-detecting the presence of an agent. To disable the +agent check, set the disable-agent-check option to +true. + + +Disabling the agent check: + +global + disable-agent-check true +end global + + + + + + diff --git a/doc/index.docbook b/doc/index.docbook index 4e6f9d31..2e8306bb 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -77,6 +77,7 @@ + ]> @@ -1466,39 +1467,7 @@ do with this tool. - -Features for developers - - - Agent checks - can ensure that developers that use to -access the source repository do not accidentally forget to leave the - Agent tool enabled. This can cause to hang indefinitely -waiting for the developer to type in their password, -so by default will check if the Agent is running before -performing source updates. - - -This is only done for developers using . - - -You may wish to disable the Agent check, in case of situations where - is mis-detecting the presence of an agent. To disable the -agent check, set the disable-agent-check option to -true. - - -Disabling the agent check: - -global - disable-agent-check true -end global - - - - - - + Other features
[sdk/kdesrc-build] doc: doc: credits-and-license - separate docbook
Git commit 5aafd47afe7290dbac48570dfcacc716823b53f3 by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'. doc: credits-and-license - separate docbook A +7-0doc/credits-and-license.docbook M +2-7doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/5aafd47afe7290dbac48570dfcacc716823b53f3 diff --git a/doc/credits-and-license.docbook b/doc/credits-and-license.docbook new file mode 100644 index ..c1cde3c6 --- /dev/null +++ b/doc/credits-and-license.docbook @@ -0,0 +1,7 @@ + +Credits And License + + + + + diff --git a/doc/index.docbook b/doc/index.docbook index 12020c0d..4e6f9d31 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -76,6 +76,7 @@ + ]> @@ -1674,13 +1675,7 @@ as of version 1.6.3. - -Credits And License - - - - - +
[sdk/kdesrc-build] doc: doc: building-and-troubleshooting - separate docbook
Git commit 018dba9a0efa4a8ed0db24f8276a805f03c843f3 by Andrew Shark. Committed on 05/01/2024 at 19:57. Pushed by ashark into branch 'master'. doc: building-and-troubleshooting - separate docbook A +139 -0doc/building-and-troubleshooting.docbook M +2-139 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/018dba9a0efa4a8ed0db24f8276a805f03c843f3 diff --git a/doc/building-and-troubleshooting.docbook b/doc/building-and-troubleshooting.docbook new file mode 100644 index ..b9d478eb --- /dev/null +++ b/doc/building-and-troubleshooting.docbook @@ -0,0 +1,139 @@ + +Using the script +With the configuration data established, now you are ready to run the +script. Even if you still have some tweaking or other reading you wish to do, +it is a good idea to at least load the project metadata. + + +Loading project metadata + + +From a terminal window, log in to the user you are using to compile software and +execute the script: + + + kdesrc-build --metadata-only + + +This command will setup the source directory and connect to the KDE +repositories to download the database of git repositories, and the +database of dependency metadata, without making any further changes. It is +useful to run this separately as this metadata is useful for other + commands. + + + + +Previewing what will happen when kdesrc-build runs + +With the project metadata installed, it is possible to preview what + will do when launched. This can be done with the --pretend command line option. + + + ./kdesrc-build --pretend + + +You should see a message saying that some packages were successfully built (although +nothing was actually built). If there were no significant problems shown, you can proceed +to actually running the script. + + + kdesrc-build + + +This command will download the appropriate source code, build and install each module in order. Afterwards, you should see output similar to that in : + + +Example output of a kdesrc-build run + + kdesrc-build +Updating kde-build-metadata (to branch master) +Updating sysadmin-repo-metadata (to branch master) + +Building libdbusmenu-qt (1/200) +No changes to libdbusmenu-qt source, proceeding to build. +Compiling... succeeded (after 0 seconds) +Installing.. succeeded (after 0 seconds) + +Building taglib (2/200) +Updating taglib (to branch master) +Source update complete for taglib: 68 files affected. +Compiling... succeeded (after 0 seconds) +Installing.. succeeded (after 0 seconds) + +Building extra-cmake-modules from module-set at line 32 (3/200) +Updating extra-cmake-modules (to branch master) +Source update complete for extra-cmake-modules: 2 files affected. +Compiling... succeeded (after 0 seconds) +Installing.. succeeded (after 0 seconds) + +... + +Building kdevelop from kdev (200/200) +Updating kdevelop (to branch master) +Source update complete for kdevelop: 29 files affected. +Compiling... succeeded (after 1 minute, and 34 seconds) +Installing.. succeeded (after 2 seconds) + + PACKAGES SUCCESSFULLY BUILT +Built 200 modules + +Your logs are saved in /home/kde-src/kdesrc/log/2018-01-20-07 + + + + + +Resolving build failures + + +Depending on how many modules you are downloading, it is possible that + will not succeed the first time you compile software. +Do not despair! + + + logs the output of every command it runs. By default, +the log files are kept in ~/kdesrc/log. To see what +the caused an error for a module in the last command, usually +it is sufficient to look at ~/kdesrc/log/latest/module-name/error.log. + +Perhaps the easiest way to find out what error caused a module to +fail to build is to search backward with a case-insensitive search, starting +from the end of the file looking for the word error. Once +that is found, scroll up to make sure there are no other error messages nearby. +The first error message in a group is usually the underlying +problem. + +In that file, you will see the error that caused the build to fail for +that module. If the file says (at the bottom) that you are missing some +packages, try installing the package (including any appropriate -dev packages) +before trying to build that module again. Make sure that when you run + again to pass the --reconfigure option so that + forces the module to check for the missing packages +again. + +Or, if the error appears to be a build error (such as a syntax error, +incorrect prototype, unknown type, or similar) +then it is probably an error with the source, which will hopefully be +resolved within a few days. If it is not resolved within that time, feel free +to mail the kde-de...@kde.org mailing list (subscription may be +required first) in order to report the build failure. + +You can find more common examples of things that can go wrong and their +solutions, as well as general tips and strategies to build
[sdk/kdesrc-build] doc: doc: advanced-features - separate docbook
Git commit a26d6653d49bb5284edf92a74569bca09f0c681e by Andrew Shark. Committed on 05/01/2024 at 19:56. Pushed by ashark into branch 'master'. doc: advanced-features - separate docbook A +420 -0doc/advanced-features.docbook M +6-420 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/a26d6653d49bb5284edf92a74569bca09f0c681e diff --git a/doc/advanced-features.docbook b/doc/advanced-features.docbook new file mode 100644 index ..edb19da7 --- /dev/null +++ b/doc/advanced-features.docbook @@ -0,0 +1,420 @@ + +Advanced features + + +Partially building a module +It is possible to build only pieces from a single module. For +example, you may want to compile only one program from a module. +has features to make this easy. There are several complementing ways to +do this. + + + +Removing directories from a build +It is possible to download an entire repository +but have the build system leave out a few directories when it does +the build. This requires that the module uses and that the +module's build system allows the directory to remove to be +optional. + + +This is controlled with the option. + + +This option requires at least that the +build system for the module is reconfigured after changing +it. This is done using the kdesrc-build + +module command. + + + +To remove the python directory +from the kdebindings build process: + + +module kdebindings + python +end module + + + + +This function depends on some standard conventions used in most + modules. Therefore it may not work for all programs. + + + + + + +Branching and tagging support for + + +What are branches and tags? + + supports managing the history of the source code. +uses this support to create branches for development, and to tag the repository +every so often with a new version release. + + +For example, the developers may be working on a new feature in +a different branch in order to avoid breaking the version being used by most +developers. This branch has development ongoing inside it, even while the +main branch (called master) may have development going on inside of it. + + +A tag, on the other hand, is a specified point in the source code repository +at a position in time. This is used by the administration team to mark +off a version of code suitable for release and still allow the developers to +work on the code. + + + + + +How to use branches and tags + +Support for branches and tags is handled by a set of options, which +range from a generic request for a version, to a specific to download +for advanced users. + + +The easiest method is to use the and options. You simply +use the option along with the name of the desired branch or tag for a module, +and will try to determine the appropriate location within the + repository to download from. For most modules this works very +well. + + +To download kdelibs from 4.6 (which is simply known as the 4.6 branch): + + + +module kdelibs + branch 4.6 + # other options... +end module + + +Or, to download kdemultimedia as it was released with 4.6.1: + + +module kdemultimedia + tag 4.6.1 + # other options... +end module + + + + +You can specify a global branch value. But if you do so, do not forget +to specify a different branch for modules that should not use the global branch! + + + + + + +Stopping the build early + + +The build normally continues even if failures occur + + normally will update, build and install all modules +in the specified list of modules to build, even if a module fails to build. +This is usually a convenience to allow you to update software packages even +if a simple mistake is made in one of the source repositories during +development that causes the build to break. + + + +However you may wish for to stop what it is doing once a +module fails to build and install. This can help save you time that will be +wasted trying to make progress when modules remaining in the build list will +not be able to successfully build either, especially if you have not ever +successfully built the modules in the list. + + + + + +Not stopping early with --no-stop-on-failure + + +The primary method to do this is to use the +--no-stop-on-failure +command line option when you run . + + +This option can also be set in the +configuration file to make +it the normal mode of operation. + + +It is also possible to tell at runtime to stop building +after completing the current module it is working on. +This is as opposed to interrupting using a command like +C, which interrupts + immediately, losing the progress of the current module. + + +Interrupting during a module install when +the use-clean-install option +is enabled will mean that the interrupted module will be unavailable until + is able to successfully build the module! + +If you need to interrupt without permitting a graceful shutdown +in this situation, at least try to avoid doing this while is +installing a module. + + + + + +Stopping gracefully when stop-on-failure is false
[sdk/kdesrc-build] doc: doc: basic-features - separate docbook
Git commit 097dee86e82f4d4c6adefea1884686475454f896 by Andrew Shark. Committed on 05/01/2024 at 19:57. Pushed by ashark into branch 'master'. doc: basic-features - separate docbook A +209 -0doc/basic-features.docbook M +2-209 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/097dee86e82f4d4c6adefea1884686475454f896 diff --git a/doc/basic-features.docbook b/doc/basic-features.docbook new file mode 100644 index ..2331e2ab --- /dev/null +++ b/doc/basic-features.docbook @@ -0,0 +1,209 @@ + +Basic features + + +qt support + supports building the toolkit used by software +as a convenience to users. This support is handled by a special module named +qt. + + is developed under a separate repository from software +located at http://code.qt.io/cgit/qt/;>http://code.qt.io/cgit/qt/. + +In order to build , you should make sure that the +qtdir setting is set to the directory you'd +like to install to, as described in . + +You should then ensure that the qt module is added to +your .kdesrc-buildrc, before any other modules in the +file. If you are using the sample configuration file, you can simply +uncomment the existing qt module entry. + +Now you should verify the repository option and branch options are set appropriately: + + +The first option is to build using a mirror maintained +on the source repositories (no other changes are applied, it is simply +a clone of the official source). This is highly recommended due to occasional +issues with cloning the full module from its official repository. + +You can set the repository option for the qt +module to kde:qt to use this option. + + +Otherwise, to build the standard , set your +repository option to +git://gitorious.org/qt/qt.git. Note that you may +experience problems performing the initial clone of from this +repository. + + +In both cases, the branch option should be set to master (unless you'd +like to build a different branch). + + + + +Standard flags added by +Nota Bene: this section does not apply to modules for which you have +configured a custom toolchain, using e.g. +cmake-toolchain. + +To save you time, adds some standard paths to your +environment for you: + + + + +The path to the and libraries is added to the +LD_LIBRARY_PATH variable automatically. This means that you +do not need to edit to include them. + + + +The path to the and development support programs are added to the +PATH variable automatically. This means that you do not need to +edit to include them. + + + +The path to the -provided pkg-config is added +automatically to PKG_CONFIG_PATH. This means that you do not +need to use to add these. + + + +The setting for is automatically propagated to the QTDIR +environment variable while building. + + + + + + + +Changing 's build priority +Programs can run with different priority levels on Operating Systems, +including and . This allows the system to allocate time for the +different programs in accordance with how important they are. + + + will normally allocate itself a low priority so that the +rest of the programs on your system are unaffected and can run normally. +Using this technique, will use extra CPU when it is available. + + + will still maintain a high enough priority level so that +it runs before routine batch processes and before CPU donation programs +such as http://setiathome.ssl.berkeley.edu/;>Seti@Home. + + +To alter so that it uses a higher (or lower) priority +level permanently, then you need to adjust the setting in the configuration file. The setting +controls how nice is to other programs. In other +words, having a higher gives a lower priority. So to +give a higher priority, reduce the (and vice versa). +The can go from 0 (not nice at all, highest priority) to 20 (super +nice, lowest priority). + +You can also temporarily change the priority for by using +the command line option. The value to +the option is used exactly the same as for . + +It is possible for some programs run by the super user to have a +negative nice value, with a correspondingly even higher priority for such +programs. Setting a negative (or even 0) for is not +a great idea, as it will not help run time significantly, but will make your +computer seem very sluggish should you still need to use it. + + + +To run with a niceness of 15 (a lower priority than +normal): + + + kdesrc-build --nice=15 + + +Or, you can edit the configuration file to make the change permanent: + + + 15 + + + + +The niceness option only affects the +usage of the computer's processor(s). One other major affect on computer +performance relates to how much data input or output (I/O) a +program uses. In order to control how much I/O a program can +use, modern operating systems support a similar tool called +ionice. supports +ionice, (but only to enable or disable it +completely) using the use-idle-io-priority option, +since version 1.12. + + + + + + +Installation as the superuser +You may wish to have
[sdk/kdesrc-build] doc: doc: appendix-profile - separate docbook
Git commit 047ca98d497befc8ab630c0769b34f1d34803b87 by Andrew Shark.
Committed on 05/01/2024 at 19:57.
Pushed by ashark into branch 'master'.
doc: appendix-profile - separate docbook
A +168 -0doc/appendix-profile.docbook
M +2-168 doc/index.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/047ca98d497befc8ab630c0769b34f1d34803b87
diff --git a/doc/appendix-profile.docbook b/doc/appendix-profile.docbook
new file mode 100644
index ..a9293a92
--- /dev/null
+++ b/doc/appendix-profile.docbook
@@ -0,0 +1,168 @@
+
+Superseded profile setup procedures
+
+
+Setting up a login profile
+
+These instructions cover how to setup the profile required to ensure your
+computer can login to your newly-built desktop.
+will normally try to do this automatically (see ). This appendix section can be useful for those who
+cannot use 's support for login profile setup. However the
+instructions may not always be up-to-date, it can also be useful to consult the
+kde-env-master.sh.in file included with the
+source.
+
+
+Changing your startup profile settings
+
+The .bash_profile is the login settings
+file for the popular bash shell used by many
+distributions. If you use a different shell, then you may need to adjust the
+samples given in this section for your particular shell.
+
+
+Open or create the .bash_profile file in the home
directory with your favorite editor,
+and add to the end of the file:
+
+If you are building the qt module (you are by default), add instead:
+
+
+QTDIR=(path to qtdir) # Such as ~/kdesrc/build/qt by default.
+PATH=${install-dir}/bin:$QTDIR/bin:$PATH
+MANPATH=$QTDIR/doc/man:$MANPATH
+
+# Act appropriately if LD_LIBRARY_PATH is not already set.
+if [ -z $LD_LIBRARY_PATH ]; then
+ LD_LIBRARY_PATH=${install-dir}:/lib:$QTDIR/lib
+else
+ LD_LIBRARY_PATH=${install-dir}:/lib:$QTDIR/lib:$LD_LIBRARY_PATH
+fi
+
+export QTDIR PATH MANPATH LD_LIBRARY_PATH
+
+
+or, if you are not building qt (and are using your system instead), add
+this instead:
+
+
+PATH=${install-dir}/bin:$QTDIR/bin:$PATH
+
+# Act appropriately if LD_LIBRARY_PATH is not already set.
+if [ -z $LD_LIBRARY_PATH ]; then
+ LD_LIBRARY_PATH=${install-dir}/lib
+else
+ LD_LIBRARY_PATH=${install-dir}/lib:$LD_LIBRARY_PATH
+fi
+
+export PATH LD_LIBRARY_PATH
+
+
+
+
+If you are not using a dedicated user, set a different $KDEHOME
+for your new environment in your .bash_profile:
+
+
+export KDEHOME="${HOME}/.kde-git"
+
+# Create it if needed
+[ ! -e ~/.kde-git ] mkdir ~/.kde-git
+
+
+
+
+
+If later your K Menu is empty or too crowded with applications from your
+distribution, you may have to set the XDG environment
+variables in your .bash_profile:
+
+
+XDG_CONFIG_DIRS="/etc/xdg"
+XDG_DATA_DIRS="${install-dir}/share:/usr/share"
+export XDG_CONFIG_DIRS XDG_DATA_DIRS
+
+
+
+
+
+
+
+Starting
+
+
+Now that you have adjusted your environment settings to use the correct ,
+it is important to ensure that the correct startkde script
+is used as well.
+
+
+
+Open the .xinitrc text file from the home directory, or
+create it if necessary. Add the line:
+
+
+exec ${install-dir}/bin/startkde
+
+
+
+On some distributions, it may be necessary to perform the same
+steps with the .xsession file, also in the home directory.
+This is especially true when using graphical login managers such as
+sddm, gdm, or xdm.
+
+
+
+Now start your fresh : in and systems with virtual terminal
support,
+F1 ...
F12 keystroke
combinations are used to switch to Virtual Console 1 through 12.
+This allows you to run more than one desktop environment at the same time. The
fist six are
+text terminals and the following six are graphical displays.
+
+
+
+If when you start your computer you are presented to the graphical display
+manager instead, you can use the new environment, even if it is not
listed
+as an option. Most display managers, including sddm, have an option to use
+a Custom Session when you login. With this option, your session
settings are
+loaded from the .xsession file in your home directory. If
+you have already modified this file as described above, this option should load
+you into your new installation.
+
+
+If it does not, there is something else you can try that should normally
+work: Press F2,
+and you will be presented to a text terminal. Log in using the dedicated user
+and type:
+
+
+
+startx -- :1
+
+
+
+
+You can run the from sources and the old at the same time! Log in
+using your regular user, start the stable desktop. Press F2 (or
+F1, F3, etc..), and you will be presented
+with a text terminal. Log in using the dedicated user and
+type:
+
+
+startx -- :1
+
+
+You can go back to the desktop of your regular user by pressing the
+shortcut key for the already running desktop. This is normally
+F7, you may
need
+to use F6 or F8 instead. To return to your
+-compiled , you would use the same sequence, except with the
+next function key. For example, if you needed to enter F7
+to switch to your regular , you would
[sdk/kdesrc-build] doc: doc: building-specific-modules - separate docbook
Git commit 70175b26036e7cd31776b4c8a45d49de2bd1abab by Andrew Shark. Committed on 05/01/2024 at 19:58. Pushed by ashark into branch 'master'. doc: building-specific-modules - separate docbook A +62 -0doc/building-specific-modules.docbook M +2-62 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/70175b26036e7cd31776b4c8a45d49de2bd1abab diff --git a/doc/building-specific-modules.docbook b/doc/building-specific-modules.docbook new file mode 100644 index ..d0e30a76 --- /dev/null +++ b/doc/building-specific-modules.docbook @@ -0,0 +1,62 @@ + +Building specific modules + +Rather than building every module all the time, you may only want to build a single +module, or other small subset. Rather than editing your configuration file, you can simply +pass the names of modules or module sets to build to the command line. + + +Example output of a kdesrc-build specific module build + + kdesrc-build --include-dependencies dolphin +Updating kde-build-metadata (to branch master) +Updating sysadmin-repo-metadata (to branch master) + +Building extra-cmake-modules from frameworks-set (1/79) +Updating extra-cmake-modules (to branch master) +No changes to extra-cmake-modules source, proceeding to build. +Running cmake... +Compiling... succeeded (after 0 seconds) +Installing.. succeeded (after 0 seconds) + +Building phonon from phonon (2/79) +Updating phonon (to branch master) +No changes to phonon source, proceeding to build. +Compiling... succeeded (after 0 seconds) +Installing.. succeeded (after 0 seconds) + +Building attica from frameworks-set (3/79) +Updating attica (to branch master) +No changes to attica source, proceeding to build. +Compiling... succeeded (after 0 seconds) +Installing.. succeeded (after 0 seconds) + +... + +Building dolphin from base-apps (79/79) +Updating dolphin (to branch master) +No changes to dolphin source, proceeding to build. +Compiling... succeeded (after 0 seconds) +Installing.. succeeded (after 0 seconds) + + PACKAGES SUCCESSFULLY BUILT +Built 79 modules + +Your logs are saved in /home/kde-src/kdesrc/log/2018-01-20-07 + + + +In this case, although only the dolphin +application was specified, the --include-dependencies flag +caused to include the dependencies listed for +dolphin (by setting the include-dependencies option). + + +The dependency resolution worked in this case only because +dolphin happened to be specified in a +kde-projects-based module set (in this example, named +base-apps). See . + + + diff --git a/doc/index.docbook b/doc/index.docbook index f7462149..55314add 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -72,6 +72,7 @@ + ]> @@ -544,68 +545,7 @@ which is described in . - -Building specific modules - -Rather than building every module all the time, you may only want to build a single -module, or other small subset. Rather than editing your configuration file, you can simply -pass the names of modules or module sets to build to the command line. - - -Example output of a kdesrc-build specific module build - - kdesrc-build --include-dependencies dolphin -Updating kde-build-metadata (to branch master) -Updating sysadmin-repo-metadata (to branch master) - -Building extra-cmake-modules from frameworks-set (1/79) -Updating extra-cmake-modules (to branch master) -No changes to extra-cmake-modules source, proceeding to build. -Running cmake... -Compiling... succeeded (after 0 seconds) -Installing.. succeeded (after 0 seconds) - -Building phonon from phonon (2/79) -Updating phonon (to branch master) -No changes to phonon source, proceeding to build. -Compiling... succeeded (after 0 seconds) -Installing.. succeeded (after 0 seconds) - -Building attica from frameworks-set (3/79) -Updating attica (to branch master) -No changes to attica source, proceeding to build. -Compiling... succeeded (after 0 seconds) -Installing.. succeeded (after 0 seconds) - -... - -Building dolphin from base-apps (79/79) -Updating dolphin (to branch master) -No changes to dolphin source, proceeding to build. -Compiling... succeeded (after 0 seconds) -Installing.. succeeded (after 0 seconds) - - PACKAGES SUCCESSFULLY BUILT -Built 79 modules - -Your logs are saved in /home/kde-src/kdesrc/log/2018-01-20-07 - - - -In this case, although only the dolphin -application was specified, the --include-dependencies flag -caused to include the dependencies listed for -dolphin (by setting the include-dependencies option). - - -The dependency resolution worked in this case only because -dolphin happened to be specified in a -kde-projects-based module set (in this example, named -base-apps). See . - - - + Setting the
[sdk/kdesrc-build] doc: doc: appendix-modules - separate docbook
Git commit b9d905dff7bf8aaa0d943d96bac2bf69494161fe by Andrew Shark. Committed on 05/01/2024 at 19:56. Pushed by ashark into branch 'master'. doc: appendix-modules - separate docbook A +131 -0doc/appendix-modules.docbook M +2-131 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/b9d905dff7bf8aaa0d943d96bac2bf69494161fe diff --git a/doc/appendix-modules.docbook b/doc/appendix-modules.docbook new file mode 100644 index ..109f2daf --- /dev/null +++ b/doc/appendix-modules.docbook @@ -0,0 +1,131 @@ + + modules and source code organization + +The Module + + groups its software into modules of various size. +This was initially a loose grouping of a few large modules, but with the +introduction of the https://git-scm.com/;>Git-based https://commits.kde.org/;>source code repositories, these large +modules were further split into many smaller modules. + + + uses this module concept as well. In essence, a +module is a grouping of code that can be downloaded, built, +tested, and installed. + + + +Individual modules + +It is easy to set to build a single module. The following +listing is an example of what a declaration for a Git-based module would +look like in the configuration +file. + + +module kdefoo +cmake-options -DCMAKE_BUILD_TYPE=Debug +end module + + +This is a Git-based module since it doesn't use a repository option. Also, the +cmake-options option is listed as an example only, it is not +required. + + + +Groups of related modules + +Now most source modules are Git-based , and are normally +combined into groups of modules. + + therefore supports groups of modules as well, using +module sets. An example: + + +module-set base-modules +repository kde-projects +use-modules kde-runtime kde-workspace kde-baseapps +end module-set + + +You can leave the module set name (base-modules +in this case) empty if you like. This repository setting tells + where to download the source from, but you can also use a +git:// URL. + +One special feature of the repository +kde-projects is that will +automatically include any Git modules that are grouped under the modules you +list (in the KDE Project database). + + + +Module branch groups + +Taking the concept of a group of +modules further, the developers eventually found that +synchronizing the names of the Git branches across a large number of +repositories was getting difficult, especially during the development push for +the new Frameworks for 5. + + +So the concept of branch groups was developed, to allow +users and developers to select one of only a few groups, and allow the script +to automatically select the appropriate Git branch. + + + supports this feature as of version 1.16-pre2, via the +branch-group option. + + + +Example of using branch-group + +branch-group can be used in the configuration file as follows: + + + +global +# Select KDE Frameworks 5 and other Qt5-based apps +branch-group kf5-qt5 + +# Other global options here ... +end global + +module-set +# branch-group only works for kde-projects +repository kde-projects + +# branch-group is inherited from the one set globally, but could +# specified here. + +use-modules kdelibs kde-workspace +end module-set + +# kdelibs's branch will be "frameworks" +# kde-workspace's branch will be "master" (as of August 2013) + + +In this case the same branch-group gives different +branch names for each Git module. + + + +This feature requires some data maintained by the developers in a Git +repository named kde-build-metadata, however this module +will be included automatically by (though you may see it appear +in the script output). + + + modules that do not have a set branch name for the branch +group you choose will default to an appropriate branch name, as if you had not +specified branch-group at all. + + + + + + diff --git a/doc/index.docbook b/doc/index.docbook index 228b67bb..db3eddcf 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -68,6 +68,7 @@ Just add them as necessary. --> + ]> @@ -4388,137 +4389,7 @@ as of version 1.6.3. - - modules and source code organization - -The Module - - groups its software into modules of various size. -This was initially a loose grouping of a few large modules, but with the -introduction of the https://git-scm.com/;>Git-based https://commits.kde.org/;>source code repositories, these large -modules were further split into many smaller modules. - - - uses this module concept as well. In essence, a -module is a grouping of code that can be downloaded, built, -tested, and installed. - - - -Individual modules - -It is easy to set to build a single module. The following -listing is an example of what a declaration for a Git-based module would -look like in the configuration -file. - - -module kdefoo -cmake-options -DCMAKE_BUILD_TYPE=Debug -end module - - -This is a Git-based module since it doesn't use a repository option. Also, the -cmake-options
