# kdesrc-build

## QUICK HOWTO

1. Install kdesrc-build:
    - Copy the kdesrc-build directory (i.e. the directory holding this README)
      somewhere where you will be able to find it. The whole directory has to
      go together, so don't just copy the script itself.

    - Alternately, you can run the `git` command itself to easily install
      kdesrc-build:

      $ mkdir -p ~/kdesrc
      $ cd ~/kdesrc
      $ git clone git://anongit.kde.org/kdesrc-build
      $ cd kdesrc-build # kdesrc-build is in this directory

2. Setup:
    - **For KDE 4 Platform and Plasma Desktop**: If you don't already have a
      ~/.kdesrc-buildrc, use the kdesrc-build-setup program to make one, or
      copy kdesrc-buildrc-sample to ~/.kdesrc-buildrc and make any changes that
      you need.

    - **For KDE Frameworks ("KF5") / Plasma 5**: Please take a look at 
      `kdesrc-build-kf5-sample` in the kdesrc-build directory,
      which gives a starting point example for a suitable ~/.kdesrc-buildrc.

    - the `kdesrc-buildrc-sample` file in the kdesrc-build directory
      gives a few hints at what options are available. Also, look at the 
      documentation at
      https://docs.kde.org/trunk5/en/extragear-utils/kdesrc-build/conf-options-table.html

3. From the kdesrc-build directory, run "./kdesrc-build --metadata-only". This
   will download some data that describes the KDE source repositories and their
   dependencies, which will help kdesrc-build figure out what to build.

4. Now you can run "kdesrc-build --pretend" to have kdesrc-build go through the
   steps that it would perform, but without actually doing them. This is a good
   time to make sure that kdesrc-build is set the way you want it.

5. When you're ready, run "./kdesrc-build". Hopefully everything will go well
   the first time, and kdesrc-build will be able to download and build all of
   the modules that you ask for. :)

## UPGRADING KDESRC-BUILD

Upgrading is simple.

You can delete your old kdesrc-build directory (make sure you don't have any
local changes in there first, or your kdesrc-buildrc file!) and then install
the new version where the old kdesrc-build directory used to be.

In fact, it is recommended to use git to update kdesrc-build itself, so that
kdesrc-build is kept upgraded automatically. This is mostly done in the sample
configuration for KF5, where kdesrc-build is configured to update itself,
however for the best success you should remember to add the kdesrc-build git
repository to your PATH environment variable.

One thing to keep in mind when using kdesrc-build to manage keeping itself
up to date is that updates won't take effect until the *next* time you run
kdesrc-build.

You may want to edit your ~/.kdesrc-buildrc to make sure any new
options are included. You should always read the changes for the new version
however, as sometimes there are slight changes in behavior necessary to adapt
to updates in the source repository. If you are running kdesrc-build from its
git repository, you can use the "git log" command from inside the kdesrc-build
source directory to see the latest changes.

You can use the `./kdesrc-build --version` command to ensure that you have
successfully upgraded kdesrc-build.

## SAMPLE CONFIGURATION

A sample configuration file is included.  It should work for you for the most
part with only minor tweaking.  To use it, just copy it to ~/.kdesrc-buildrc.

Alternatively, a program is included called kdesrc-build-setup, which can be
used to generate a simple configuration (for KDE4-based builds).

## HELP!!!

kdesrc-build includes a limited command-line description with the
--help option.

You can read the kdesrc-build handbook online at
https://docs.kde.org/index.php?application=kdesrc-build

If you have already setup a KDE build environment then kdesrc-build itself can
have its documentation compiled and installed.
In this case the documentation is available in Konqueror (help:/kdesrc-build)
or KHelpCenter. Additionally a man page will be installed, or you can run "man
./kdesrc-build.1" in the "doc/" directory of kdesrc-build's own build
directory.

You can also ask for help online on the #kde-devel channel of IRC (irc.kde.org).

Additionally you can ask for help on the KDE support mailing lists, such as
kde-devel@kde.org

Finally you can drop me an email at mpyne@kde.org (although I have a job/family
and therefore don't always have time to respond)

## UPDATES / CONTACT INFO

You can find updated versions of kdesrc-build online as part of the
extragear/utils module: (You can also see the change log this way)

https://projects.kde.org/projects/extragear/utils/kdesrc-build

In fact, it is unlikely that future releases will be made. Though new versions
will be tagged, they will not be released as source tarballs. You should run
from git (it is likely a 'stable' branch will be setup to make this more
feasible)

If you find a bug, please report it at:
  https://bugs.kde.org/

If you have any questions, feel free to let me know:
  Michael Pyne <mpyne@kde.org>