Warning, /sdk/kdesrc-build/README.md is written in an unsupported language. File is not indexed.

0001 # kdesrc-build
0002 
0003 This script streamlines the process of setting up and maintaining a development
0004 environment for KDE software.
0005 
0006 It does this by automating the process of downloading source code from the
0007 KDE source code repositories, building that source code, and installing it
0008 to your local system.
0009 
0010 ## Note the Alternatives
0011 
0012 NOTICE!
0013 
0014 If you are a power user just trying to test the latest KDE releases like [KDE
0015 Plasma 5](https://www.kde.org/plasma-desktop) or the [KDE
0016 Applications](https://www.kde.org/applications/) then there are potentially
0017 easier options you may wish to consider first. KDE provides a quick-starter
0018 distribution, [KDE neon Developer Edition](https://neon.kde.org/download), and
0019 your favorite distribution may also have <q>bleeding edge</q> packages that may
0020 be easier to try out.
0021 
0022 However if you're testing out the latest KDE Frameworks or are involved in
0023 development yourself, you'll probably find it easiest to use kdesrc-build.
0024 Continue on, to learn how to set it up.
0025 
0026 ## QUICK HOWTO
0027 
0028 1. Set up minimum dependencies
0029 
0030 - You must have at least [Perl](https://www.perl.org/get.html) version 5.26
0031   installed. Most distributions include at least a minimal Perl set up, and
0032   Perl is also required for some portions of Qt and KDE software builds so it
0033   is good to have regardless.
0034 
0035 - You must have [Git](https://git-scm.com/) installed to download KDE sources
0036   and kdesrc-build itself. Any supported version should be fine but We
0037   recommend at least version 2.26.
0038 
0039 - If you wish to run the interactive setup script you must have [dialog](https://invisible-island.net/dialog/)
0040   installed.
0041 
0042 2. Install kdesrc-build:
0043 
0044 - Clone kdesrc-build from git, by running from a terminal:
0045 
0046 ```shell
0047 $ mkdir -p ~/kde/src
0048 $ cd ~/kde/src
0049 $ git clone https://invent.kde.org/sdk/kdesrc-build.git
0050 $ cd kdesrc-build # kdesrc-build is in this directory
0051 ```
0052 
0053 - Make sure it works by running:
0054 
0055 ```shell
0056 $ cd ~/kde/src/kdesrc-build
0057 $ ./kdesrc-build --version
0058 ```
0059 
0060 You should see output similar to `kdesrc-build 18.10 (v18.10-20-g1c39943)`.
0061 Later we will set up kdesrc-build to keep itself updated automatically.
0062 
0063 2. Set up kdesrc-build:
0064 
0065 - Now that kdesrc-build is installed and works, you need to set up kdesrc-build
0066   to work appropriately on your particular system. Do this by running the
0067   provided set up script to generate the **configuration file**
0068   (~/.config/kdesrc-buildrc):
0069 
0070 ```shell
0071 $ cd ~/kde/src/kdesrc-build
0072 $ ./kdesrc-build-setup
0073 ```
0074 
0075 - Answer the questions given, but do not fret if you don't know what exactly
0076   you want to build, it is easy to edit the configuration later or just to
0077   re-run `kdesrc-build-setup` again.
0078 
0079 - This script will reference a standard configuration provided as part of the
0080   kdesrc-build repository that you downloaded earlier. As kdesrc-build
0081   self-updates, these changes will reflect for your configuration as well.
0082 
0083 - After a configuration has been generated, kdesrc-build is able to bootstrap
0084   its environment on most distributions by running:
0085 ```shell
0086 $ ./kdesrc-build --initial-setup
0087 ```
0088   This will install the dependencies required by kdesrc-build as well as add
0089   itself to your path for convenience.
0090 
0091 3. Download the KDE project and dependency data:
0092 
0093 ```shell
0094 $ cd ~/kde/src/kdesrc-build
0095 $ ./kdesrc-build --metadata-only
0096 ```
0097 
0098 This will download information describing the KDE source repositories and
0099 their dependencies, which will help kdesrc-build figure out what to build.
0100 
0101 kdesrc-build will maintain this automatically, but running this step separately
0102 helps to verify that kdesrc-build can properly reach the KDE source repository
0103 and allows the `--pretend` option in the next step to provide more accurate
0104 output.
0105 
0106 4. Verify kdesrc-build has a good build plan:
0107 
0108 ```shell
0109 $ cd ~/kde/src/kdesrc-build
0110 $ ./kdesrc-build --pretend
0111 ```
0112 
0113 This will have kdesrc-build go through the steps that it would perform, but
0114 without actually doing them. kdesrc-build will do some basic pre-checks in this
0115 stage to ensure that required command-line commands are available, including
0116 `cmake`, `git`, `qmake`, and others.
0117 
0118 This is the last good chance to make sure that kdesrc-build is set the way you
0119 want it. If this command gives you a message that all modules were successfully
0120 built, you can move onto the next step.
0121 
0122 5. Perform your first build:
0123 
0124 ```shell
0125 $ cd ~/kde/src/kdesrc-build
0126 $ ./kdesrc-build --stop-on-failure dolphin
0127 ```
0128 
0129 This will build [Dolphin](https://www.kde.org/applications/system/dolphin/),
0130 the Plasma 5 file manager and its KDE-based dependencies. We choose Dolphin
0131 since it is a good test case to exercise the whole build process.
0132 
0133 For each module built, kdesrc-build will complete these steps:
0134 
0135 - Update source code (initial download or later update)
0136 - Set up the build system and configure source code with your options, if needed
0137 - Perform the build, if needed
0138 - Install the module
0139 
0140 The `--stop-on-failure` flag causes kdesrc-build to stop the first time a
0141 module fails to build, in case there are missing dependencies. If not set,
0142 kdesrc-build would otherwise try to build all the modules even if some fail.
0143 
0144 Hopefully everything will go well the first time, and kdesrc-build will be able
0145 to download and build all of the modules that you ask for. :)
0146 
0147 ## UPGRADING KDESRC-BUILD
0148 
0149 Upgrading is simple.
0150 
0151 You can delete your old kdesrc-build directory (make sure you don't have any
0152 local changes in there first, or your kdesrc-buildrc file!) and then install
0153 the new version where the old kdesrc-build directory used to be.
0154 
0155 In fact, it is recommended to use git to update kdesrc-build itself, so that
0156 kdesrc-build updates itself automatically when run. This is set up already in
0157 the sample configuration for KF5, where kdesrc-build is configured to update
0158 itself.
0159 
0160 One thing to keep in mind when using kdesrc-build to manage keeping itself
0161 up to date is that updates won't take effect until the *next* time you run
0162 kdesrc-build.
0163 
0164 You may want to edit the kdesrc-buildrc configuration file to make sure any new
0165 options are included. You should always read the changes for the new version
0166 however, as sometimes there are slight changes in behavior necessary to adapt
0167 to updates in the source repository. If you are running kdesrc-build from its
0168 git repository, you can use the "git log" command from inside the kdesrc-build
0169 source directory to see the latest changes.
0170 
0171 You can use the `./kdesrc-build --version` command to ensure that you have
0172 successfully upgraded kdesrc-build.
0173 
0174 ## SAMPLE CONFIGURATION
0175 
0176 A sample configuration file is included for demonstration purposes. You could
0177 copy it to `~/.config/kdesrc-buildrc` and edit manually. However,
0178 it is advised to use provided `kdesrc-build-setup` script instead.
0179 
0180 ## HELP!!!
0181 
0182 This is only a very cursory guide. For more information please see the KDE
0183 Community [Get Involved for
0184 Development](https://community.kde.org/Get_Involved/development) page.
0185 
0186 ## REFERENCE
0187 
0188 kdesrc-build includes a limited command-line description with the --help
0189 option.
0190 
0191 You can read the [kdesrc-build
0192 handbook](https://docs.kde.org/?application=kdesrc-build) online.
0193 
0194 Once you've set up a KDE development environment, kdesrc-build itself can
0195 generate and build documentation (a handbook and a man page).
0196 
0197 The handbook would be available in KHelpCenter (help:/kdesrc-build), while the
0198 man page would be available in the KDE man pages or in the kdesrc-build build
0199 directory:
0200 
0201 ```shell
0202 $ cd ~/kde/build/kdesrc-build/doc
0203 $ man ./kdesrc-build.1
0204 ```
0205 
0206 You can also ask for help online on the #kde-devel channel of IRC (irc.kde.org).
0207 
0208 Additionally you can ask for help on the KDE support mailing lists, such as
0209 kde-devel@kde.org
0210 
0211 Finally you can drop me an email at mpyne@kde.org (although I have a job/family
0212 and therefore don't always have time to respond)
0213 
0214 ### Behind the Curtain
0215 
0216 For each build, kdesrc-build does several things:
0217 
0218 - Finds the configuration file (based on the --rc-file option or by looking for
0219   `kdesrc-buildrc` in the current directory and falling back to
0220   `~/.config/kdesrc-buildrc`)
0221 - Reads the configuration file to generate:
0222     - Default options to apply for each module
0223     - A list of modules to build. Modules can be grouped in "module-sets", but
0224       kdesrc-build converts each set to a list of modules.
0225 - Reduces the module list to modules chosen on the command line (either by name
0226   or through options like `--resume-from`).
0227 - For modules known to be KDE repositories (derived from a module-set using the
0228   special `kde-projects` repository):
0229     - If `--include-dependencies` is enabled, adds needed KDE modules into the
0230       build, then
0231     - Reorders KDE modules with respect to each other to ensure they are built
0232       in dependency order.
0233 - Builds each module in the resulting list of modules. This is broken into
0234   "phases", and each phase's output is logged to a specific directory for
0235   inspection later (by default, ~/kde/src/log).
0236 
0237 kdesrc-build takes some pains to do perform source code updates and builds in
0238 the way that a developer really would at the command line, using the same
0239 `git`, `cmake`, `make` commands a user would. This means that users are free to
0240 explore the source directory and build directory for a module without trampling
0241 on additional data maintained by kdesrc-build: kdesrc-build does nothing
0242 special in either the source or build directories.
0243 
0244 ### Important Command Line Options
0245 
0246 These options are the most useful. Others are documented at [the kdesrc-build
0247 online handbook](https://docs.kde.org/trunk5/en/kdesrc-build/kdesrc-build/cmdline.html).
0248 
0249 | option |     Description    |
0250 | ------ |  ----------------- |
0251 | `--include-dependencies` | Adds any missing modules that are needed for the modules being built. Only works for KDE modules.                                                |
0252 | `--pretend`              | Lists the actions kdesrc-build would take but doesn't actually do them. Useful for a double-check before a long build.                           |
0253 | `--resume-from`          | Starts the build from the given module instead of building all modules. Can combine with `--stop-after` or `--stop-before`.                      |
0254 | `--resume-after`         | Starts the build from *after* the given module, otherwise same as `--resume-from`.                                                               |
0255 | `--stop-before`          | Stops the build just before the given module instead of building all modules. Can combine with `--resume-from` or `--resume-after`.              |
0256 | `--stop-after`           | Stops the build just *after* the given module, otherwise the same as `--stop-before`.                                                            |
0257 | `--no-src`               | Perform module builds as normal but don't try to update source directories. Use this when you've updated source codes yourself.                  |
0258 | `--refresh-build`        | Completely cleans under the module build directories before building. Takes more time but can help recover from a broken build directory set up. |
0259 
0260 ### Cleaning the build and install directories
0261 
0262 kdesrc-build will if possible avoid regenerating the build system and avoid
0263 complete rebuilds of existing modules. This avoids wasting significant amounts
0264 of time rebuilding source codes that have not changed, as all supported build
0265 systems are smart enough to rebuild when necessary.
0266 
0267 However it can sometimes happen that a rebuild is needed but wasn't detected.
0268 If this happens you can force a build directory to be fully rebuilt using the
0269 `--refresh-build` option to kdesrc-build.
0270 
0271 If all else fails and your development environment which was working fine now
0272 can't seem to upgrade modules anymore, another option is to consider deleting
0273 the install directory (~/kde/usr by default) completely and rebuilding
0274 everything (using `--refresh-build`), but this can take a significant amount of
0275 time!
0276 
0277 ## CONTACT INFO
0278 
0279 If you find a bug, please report it at the [KDE
0280 Bugzilla](https://bugs.kde.org/)
0281 
0282 If you have any questions, please let me know: Michael Pyne <mpyne@kde.org>