|This is a new page, currently under construction!|
KBibTeX's source is available through KDE's Git infrastructure, the repository's name is kbibtex. How to clone a Git repository is explained in the Git Recipes in TechBase. In short, run the following command in your terminal:
git clone git://anongit.kde.org/kbibtex
You can browse KBibTeX's source code at its KDE Project page.
Main development happends in the master branch (named master). It is an objective that this branch is functional and mostly stable, although it is not guaranteed. Use this branch to enjoy new features.
For releases, release branches are created. The naming scheme is kbibtex/versionnumber, where 'versionnumber' may be 0.6. Actual releases are tagged commits in such a branch, such as v0.5.1.
For bugs or features that require multiple commits and where individual commits may break master or a release branch, so-called feature branches are used. These branches are supposed to track master or a release branch. Branches for bugs are meant to be merged into the release branch where the bug was reported for and into the master branch (for future releases). Feature branches are merged into the master branch and only in rare cases back-ported to release branches. Names for bug report-related branches are bugs/bugsystem ('bugsystem' would be kde or the name of a Linux distribution) followed by the number. An example would be bugs/kde338375. Feature branches start with feature/ followed by a short descriptive name for this feature. Merged branches will be delete after some time.
The following instructions provide information how to compile KBibTeX on the command line. When compiling KBibTeX from inside of an IDE like KDevelop or Qt Creator, those settings have to be applied as well.
KBibTeX is configured using CMake. There are a few options relevant for the configuration of this project:
CMAKE_INSTALL_PREFIX:PATHspecifies the installation location. There are a number of choices available for this option:
kde4-config --prefixprints this location. Requires root permissions (e. g. via sudo). Caution: This choice will interfere with the package management.
CMAKE_BUILD_TYPEdetermines the amount of debug information included in the final code. Regular users may set it to
release, developers to
debug, and for step-by-step debugging
debugfullworks best. All available options are discussed in the CMake documentation in TechBase.
A complete example looks like this:
cmake -DCMAKE_INSTALL_PREFIX:PATH=/tmp/usr -DCMAKE_BUILD_TYPE=debug ../kbibtex
GNU Make is the default choice for source code compilation. The number of parallel processes should be specified to shorten the time to finish on multi-core systems. The priority of the compilation tasks may get reduced.
nice -n 16 make -j4
To make use of of ninja, the
cmake statement above has to include the argument
-GNinja. Combining both cmake and ninja may look like this:
cmake -GNinja -DCMAKE_INSTALL_PREFIX:PATH=/tmp/usr -DCMAKE_BUILD_TYPE=debug ../kbibtex && ninja
KBibTeX uses KDE 4's KParts technology, which requires you to install some libraries. KBibTeX may not run properly if the following steps are omitted.
Running make install will install KBibTeX into the directory as specified as installation prefix earlier. Unless the installation prefix equals KDE install directory, the following environment variables have to be specified and commands have to be executed:
KDEDIRSto include the KDE installation directory and KBibTeX's installation directory, for example /usr:/tmp/usr
LD_LIBRARY_PATHto the library directory inside the installation directory, for example /tmp/usr/lib64
XDG_DATA_HOMEto the installation directory's shared data directory, for example /tmp/usr/share
XDG_DATA_DIRSto include the shared data directories of the KDE installation directory, KBibTeX's installation directory, and other relevant prefixes, for example /usr/share:/usr/local/share:/tmp/usr/share
Now KBibTeX can be started, like shown in this example:
In below example, replace xxxx with a short and concise name for a feature to be developed (as discussed above). Branches for bugs are created similarly, but follow the scheme bugs/kdeNNNN, where NNNN is the bug number in KDE's bug tracker.
git branch --track feature/xxxx origin/master && git checkout feature/xxxx
To minimize polluting the official KBibTeX repository or when you have to write access, you may push your local branches to another Git repository to allow others to inspect your changes. In below example, personalpublicclone is your personal, public Git repository where you want to push to.
To publish you changes, use a command like this:
git push personalpublicclone feature/xxxx:feature/xxxx
Others can add your repository to their local clone of KBibTeX's git and clone your branch:
git remote add someonespublicclone email@example.com:clones/kbibtex/NAME/kbibtex # run once git fetch someonespublicclone feature/xxxx && git checkout feature/xxxx # every time to get updates git remote rm someonespublicclone && git checkout master && git branch -D feature/xxxx # to erase branch
To create a release branch from master and push it to origin, run
git checkout -b kbibtex/0.6 master && git push origin kbibtex/0.6
To tag a release in a release branch, run the following commands:
git checkout kbibtex/0.6 # be in right branch git pull --ff-only # get latest changes from origin git status # just check that everything is ok git tag -s -u GPGKEY -m "Tagging 0.6" v0.6 # actual tagging, GnuPG signed git push --tags # explicitly push tag to origin