KBibTeX/Development: Difference between revisions

    From KDE UserBase Wiki
    m (Branch 'feature/kf5' has become 'master')
    (Marked this version for translation)
    (28 intermediate revisions by 4 users not shown)
    Line 1: Line 1:
    {{Construction}}
    <languages />
    <translate>


    == Getting the Source Code ==
    == Various Useful Resources == <!--T:1-->


    KBibTeX's source is available through KDE's Git infrastructure, the repository's name is {{path|kbibtex}}. How to clone a Git repository is explained in the [https://techbase.kde.org/Development/Git/Recipes#Cloning_a_Repository Git Recipes in TechBase]. In short, run the following command in your terminal:
    <!--T:2-->
    The following links refer to other web pages or resources relevant for the development of KBibTeX.


        git clone git://anongit.kde.org/kbibtex
    <!--T:64-->
    * [https://phabricator.kde.org/project/view/176/ Phabricator project page]</translate>
    <translate>
    <!--T:65-->
    ** [https://phabricator.kde.org/source/kbibtex/ Diffusion's view on the Git repository]


    <!--T:3-->
    * [https://cgit.kde.org/kbibtex.git Git repository's webpage]
    <!--T:4-->
    * [https://bugs.kde.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=NEEDSINFO&bug_status=VERIFIED&order=changeddate%20DESC%2Cpriority%2Cbug_severity&product=KBibTeX&query_format=advanced Bug reports]
    <!--T:5-->
    * [https://build.kde.org/job/Extragear/job/kbibtex/ Continuous Integration]
    <!--T:6-->
    * [https://ebn.kde.org/krazy/reports/extragear/office/kbibtex/index.html English Breakfast Network]
    <!--T:7-->
    * [https://scan.coverity.com/projects/kbibtex Coverity Scan]
    <!--T:66-->
    * [https://t-fischer.dreamwidth.org/tag/kbibtex Blog postings on KBibTeX]
    == Quick Start to Run KBibTeX from Git == <!--T:68-->
    <!--T:69-->
    A quick and easy method to fetch, compile, and run KBibTeX from Git, i.e. the lastest code from {{path|master}} branch, is to get the [https://cgit.kde.org/scratch/thomasfischer/kbibtex-related.git/tree/run/run-kbibtex.sh {{path|run-kbibtex.sh}}] Bash script from [https://cgit.kde.org/scratch/thomasfischer/kbibtex-related.git/ Thomas Fischer's 'KBibTeX-related' Git repository].
    <!--T:70-->
    To run the script, either make it executable and run it via {{Input|./run-kbibtex.sh}} or invoke it via {{Input|bash run-kbibtex.sh}}
    <!--T:71-->
    The script will by default clone KBibTeX's Git repository into a temporary directory, compile it, install it in a temporary directory, and launch this temporary installation of KBibTeX.
    <!--T:72-->
    The script does not need to be run as root or with sudo. It will not make any permanent modifications on your system. In order to compile KBibTeX, various tools and development libraries must be available beforehand, e.g. installed via the distribution's package management system.
    <!--T:73-->
    There is a [https://cgit.kde.org/scratch/thomasfischer/kbibtex-related.git/tree/run/README.txt README.txt] file explaining the script in greater detail.
    == Getting the Source Code == <!--T:8-->
    <!--T:9-->
    KBibTeX's sources are available through KDE's Git infrastructure, the repository's name is {{path|kbibtex}}. How to clone a Git repository is explained in the [https://techbase.kde.org/Development/Git/Recipes#Cloning_a_Repository Git Recipes in TechBase]. In short, run the following command in your terminal:
    <!--T:10-->
    {{Input|git clone git://anongit.kde.org/kbibtex}}
    <!--T:11-->
    You can browse KBibTeX's source code at [https://cgit.kde.org/kbibtex.git KDE's Git server].
    You can browse KBibTeX's source code at [https://cgit.kde.org/kbibtex.git KDE's Git server].


    === Branches ===
    === Branches === <!--T:12-->


    Main development happends in the ''master branch'' (named {{path|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.
    <!--T:13-->
    Main development happens in the ''master branch'' (named {{path|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 {{path|kbibtex/}}versionnumber, where 'versionnumber' may be {{path|0.6}}. Actual releases are tagged commits within such a branch, for example {{path|v0.5.1}}. There won't be branches for bug fix releases, i.e. no {{path|kbibtex/0.6.1}}.
    <!--T:14-->
    For releases, ''release branches'' are created. The naming scheme is {{path|kbibtex/}}''versionnumber'', where ''versionnumber'' may be something like {{path|0.6}}. Actual releases are tagged commits ('tags') within such a branch, for example {{path|v0.5.1}}. There won't be branches for bug fix releases, e.g. no {{path|kbibtex/0.6.1}}.


    For bugs or features that require multiple commits and where individual commits may break {{path|master}} or a release branch, so-called ''feature branches'' are used. These branches are supposed to track {{path|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, in selected cases into releases branches where no release has been tagged yet, and only in rare cases back-ported to release branches with releases. An example for a feature branch would be {{path|feature/zotero}}, which may contain the code for an improved Zotero support. Names for bug report-related branches are {{path|bugs/}}bugsystem ('bugsystem' would be {{path|kde}} or the name of a Linux distribution) followed by the number. An example would be {{path|bugs/kde338375}}. Feature branches start with {{path|feature/}} followed by a short descriptive name for this feature. Merged feature branches will be delete after some time.
    <!--T:15-->
    For bugs or features that require multiple commits and where individual commits may break {{path|master}} or a release branch, so-called ''feature branches'' are used. These branches are supposed to track {{path|master}} (typical for features) or a release branch (typical for bugs). Branches for bugs are meant to be merged into the release branch where the bug was reported for as well as into the master branch (for future releases). Feature branches are merged into the master branch, in selected cases into releases branches where no release has been tagged yet, and only in rare cases back-ported to release branches with published releases. An example for a feature branch would be {{path|feature/zotero}}, which may contain the code for an improved Zotero support. Names for bug report-related branches are {{path|bugs/}}''bugsystemnumber'' (for example {{path|bugs/kde338375}}) , where ''bugsystem'' would be {{path|kde}} or the name of a Linux distribution and ''number'' the actual bug number. Feature branches start with {{path|feature/}} followed by a short descriptive name for this feature (all lowercase, no spaces). Merged branches will be delete after some time.


    == Compiling the Code ==
    == Compiling the Code == <!--T:16-->


    <!--T:17-->
    The following instructions provide information how to compile KBibTeX on the command line. Instructions are similar but differ slightly between KDE4-based builds (e.g. branch {{path|kbibtex/0.5}}) and KDE Frameworks 5-based builds (e.g. branch {{path|master}}). When compiling KBibTeX from inside of an IDE like KDevelop or Qt Creator, those settings have to be applied as well.
    The following instructions provide information how to compile KBibTeX on the command line. Instructions are similar but differ slightly between KDE4-based builds (e.g. branch {{path|kbibtex/0.5}}) and KDE Frameworks 5-based builds (e.g. branch {{path|master}}). When compiling KBibTeX from inside of an IDE like KDevelop or Qt Creator, those settings have to be applied as well.


    === Running CMake ===
    === Running CMake === <!--T:18-->


    <!--T:19-->
    KBibTeX is configured using CMake. There are a few options relevant for the configuration of this project:
    KBibTeX is configured using CMake. There are a few options relevant for the configuration of this project:
    # <code>CMAKE_INSTALL_PREFIX:PATH</code> specifies the installation location. There are a number of choices available for this option:
     
    ## The location of your KDE installation, for example {{Path|/usr}}. The commands <code>kde4-config --prefix</code> (compiling for KDE4) or <code>kf5-config --prefix</code> (compiling for KDE Frameworks 5) print this location. Requires root permissions (e. g. via sudo). Caution: This choice will interfere with the package management.
    <!--T:20-->
    ## A directory outside the package management's control, for example {{Path|/usr/local}}. Requires setting some environment variables as explained below. This installation stays available across reboots and is available to all users. Requires root permissions (e. g. via sudo).
    # <code>CMAKE_INSTALL_PREFIX:PATH</code> specifies the installation location. There are a number of choices available for this option:</translate>
    ## A user-writable directory like {{Path|/tmp/usr}} or {{Path|~/usr}}. Similar to above choice, it requires setting some environment variables, but no root permissions. Many distributions are configured to clean {{Path|/tmp}} on reboot.
    <translate>
    <!--T:21-->
    ## The location of your KDE installation, for example {{Path|/usr}}. The commands <code>kde4-config --prefix</code> (compiling for KDE4) or <code>kf5-config --prefix</code> (compiling for KDE Frameworks 5) print this location. Picking this option most likely will require root permissions (e. g. via sudo) for the actual installation. Caution: This choice will interfere with the package management.</translate>
    <translate>
    <!--T:22-->
    ## A directory outside the package management's control, for example {{Path|/usr/local}}. Requires setting some environment variables as explained below. This installation stays available across reboots and is available to all users. Picking this option most likely will require root permissions (e. g. via sudo) for the actual installation.</translate>
    <translate>
    <!--T:23-->
    ## A user-writable directory like {{Path|/tmp/usr}} or {{Path|~/usr}}. Similar to above choice, it requires setting some environment variables, but no root permissions. Many distributions are configured to clean {{Path|/tmp}} on reboot.</translate>
    <translate>
    <!--T:24-->
    # <code>CMAKE_BUILD_TYPE</code> determines the amount of debug information included in the final code. Regular users may set it to <code>release</code>, developers to <code>debug</code>, and for step-by-step debugging <code>debugfull</code> works best. All available options are discussed in the [https://techbase.kde.org/Development/CMake/Addons_for_KDE#Buildtypes CMake documentation in TechBase].
    # <code>CMAKE_BUILD_TYPE</code> determines the amount of debug information included in the final code. Regular users may set it to <code>release</code>, developers to <code>debug</code>, and for step-by-step debugging <code>debugfull</code> works best. All available options are discussed in the [https://techbase.kde.org/Development/CMake/Addons_for_KDE#Buildtypes CMake documentation in TechBase].


    <!--T:25-->
    A complete example looks like this:
    A complete example looks like this:
        cmake -DCMAKE_INSTALL_PREFIX:PATH=/tmp/usr -DCMAKE_BUILD_TYPE=debug ../kbibtex
    {{Input|1=cmake -DCMAKE_INSTALL_PREFIX:PATH=/tmp/usr -DCMAKE_BUILD_TYPE=debug ../kbibtex}}


    === Compiling ===
    === Compiling === <!--T:26-->


    <!--T:27-->
    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.
    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
    <!--T:28-->
    {{Input|nice -n 16 make -j$(nproc)}}


    To make use of of [https://martine.github.io/ninja/ ninja], the <code>cmake</code> statement above has to include the argument <code>-GNinja</code>. Combining both cmake and ninja may look like this:
    <!--T:29-->
    To make use of [https://ninja-build.org/ ninja], the <code>cmake</code> statement above has to include the argument <code>-GNinja</code>. Combining both cmake and ninja may look like this:


      cmake -GNinja -DCMAKE_INSTALL_PREFIX:PATH=/tmp/usr -DCMAKE_BUILD_TYPE=debug ../kbibtex && ninja
    <!--T:30-->
    {{Input|1=cmake -GNinja -DCMAKE_INSTALL_PREFIX:PATH=/tmp/usr -DCMAKE_BUILD_TYPE=debug ../kbibtex && ninja}}


    == Installation ==
    == Installation == <!--T:31-->


    <!--T:32-->
    KBibTeX uses KDE's KParts technology, which requires you to install some libraries. KBibTeX may not run properly if the following steps are omitted.
    KBibTeX uses KDE's KParts technology, which requires you to install some libraries. KBibTeX may not run properly if the following steps are omitted.


    <!--T:33-->
    Running
    Running
        make install
    {{Input|make install}}
    will install KBibTeX into the directory as specified as installation prefix earlier.
    will install KBibTeX into the directory as specified as installation prefix earlier. Depending on your choice of installation prefix, this statement has to be run with sudo or alike.
     
    <!--T:34-->
    Unless the installation prefix equals the KDE install directory, the following environment variables have to be specified. You may set the variables temporarily in an active shell session, permanently setting them in your shell's configuration, or create a small shell script that both sets those variables and then launches your custom KBibTeX installation.


    Unless the installation prefix equals KDE install directory, the following environment variables have to be specified and commands have to be executed:
    <!--T:35-->
    # '''Only for KDE4''': Set variable <code>KDEDIRS</code> to include the KDE installation directory and KBibTeX's installation directory, for example {{Path|/usr:/tmp/usr}}
    # '''Only for KDE4''': Set variable <code>KDEDIRS</code> to include the KDE installation directory and KBibTeX's installation directory, for example {{Path|/usr:/tmp/usr}}</translate>
    # '''Only for KF5''': Set variable <code>QT_PLUGIN_PATH</code> to include the plugin directory inside the library directory of KBibTeX's installation directory, for example {{Path|/usr/lib/plugins:/usr/lib/qt5/plugins:/usr/lib/qt5/plugins:/lib/kde5/plugins/:/tmp/usr/lib64/plugins/}}
    <translate>
    # Set variable <code>LD_LIBRARY_PATH</code> to the library directory inside the installation directory, for example {{Path|/tmp/usr/lib64}}
    <!--T:36-->
    # '''Only for KF5''': Set variable <code>QT_PLUGIN_PATH</code> to include the plugin directory inside the library directory of KBibTeX's installation directory, for example {{Path|/usr/lib/plugins:/usr/lib/qt5/plugins:/tmp/usr/lib64/plugins/}}</translate>
    <translate>
    <!--T:37-->
    # Set variable <code>LD_LIBRARY_PATH</code> to the library directory inside KBibTeX's installation directory, for example {{Path|/tmp/usr/lib64}}</translate>
    <translate>
    <!--T:38-->
    # Set variable <code>XDG_DATA_DIRS</code> to include the shared data directories of the KDE installation directory, KBibTeX's installation directory, and other relevant prefixes, for example {{Path|/usr/share:/usr/local/share:/tmp/usr/share}}
    # Set variable <code>XDG_DATA_DIRS</code> to include the shared data directories of the KDE installation directory, KBibTeX's installation directory, and other relevant prefixes, for example {{Path|/usr/share:/usr/local/share:/tmp/usr/share}}
    # Run <code>kbuildsycoca4</code> (KDE4) or <code>kbuildsycoca5</code> (KDE Frameworks 5)


    <!--T:39-->
    Run <code>kbuildsycoca4</code> (KDE4) or <code>kbuildsycoca5</code> (KDE Frameworks 5) to make the KDE subsystem aware of the new libraries.
    <!--T:67-->
    {{attention|KBibTeX consists of the actual program and a number of libraries. To avoid undefined behavior, it is important to uninstall any other KBibTeX installations (e.g. those done via the Linux distribution's package management system) and to remove any remaining KBibTeX libraries (e.g. those files found anywhere under {{Path|/usr}}) that match the pattern {{Path|*kbibtex*.so*}}.}}


    <!--T:40-->
    Now KBibTeX can be started, like shown in this example:
    Now KBibTeX can be started, like shown in this example:


        /tmp/usr/bin/kbibtex
    <!--T:41-->
    {{Input|/tmp/usr/bin/kbibtex}}


    == Git cookbook ==
    == Git cookbook == <!--T:42-->


    A number of pages in [https://techbase.kde.org TechBase], [https://userbase.kde.org UserBase], and [https://community.kde.org Community] discuss using Git for source code managment. This section shows some examples how Git is used for KBibTeX.
    <!--T:43-->
    A number of pages in [https://techbase.kde.org TechBase], [https://userbase.kde.org UserBase], and [https://community.kde.org Community] discuss using Git for source code management. This section shows some examples how Git is used for KBibTeX.


    === Create a Feature or Bug Branch ===
    === Create a Feature or Bug Branch === <!--T:44-->


    <!--T:45-->
    In below example, replace {{path|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 {{path|bugs/kdeNNNN}}, where NNNN is the bug number in [https://bugs.kde.org KDE's bug tracker]. Bugs in other bug trackers such as [https://gna.org/bugs/?group=kbibtex Gna!] or your distribution may use a different prefix such as {{path|bugs/gnaNNNN}} or {{path|bugs/gentooNNNN}}.
    In below example, replace {{path|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 {{path|bugs/kdeNNNN}}, where NNNN is the bug number in [https://bugs.kde.org KDE's bug tracker]. Bugs in other bug trackers such as [https://gna.org/bugs/?group=kbibtex Gna!] or your distribution may use a different prefix such as {{path|bugs/gnaNNNN}} or {{path|bugs/gentooNNNN}}.


      git branch --track feature/xxxx origin/master && git checkout feature/xxxx
    <!--T:46-->
    {{Input|1=git branch --track feature/xxxx origin/master && git checkout feature/xxxx}}


    === Pushing a Local Feature or Bug Branch ===
    === Pushing a Local Feature or Bug Branch === <!--T:47-->


    <!--T:48-->
    To minimize polluting the official KBibTeX repository or when you do not have write access, you may push your local branches to another Git repository to allow others to inspect your changes. In below example, {{path|personalpublicclone}} is your personal, public Git repository where you want to push to.
    To minimize polluting the official KBibTeX repository or when you do not have write access, you may push your local branches to another Git repository to allow others to inspect your changes. In below example, {{path|personalpublicclone}} is your personal, public Git repository where you want to push to.


    <!--T:49-->
    To publish you changes, use a command like this:
    To publish you changes, use a command like this:


        git push personalpublicclone feature/xxxx:feature/xxxx
    <!--T:50-->
    {{Input|git push personalpublicclone feature/xxxx:feature/xxxx}}


    <!--T:51-->
    Others can add your repository to their local clone of KBibTeX's git and clone your branch (assuming in this example it is located on KDE's Git server):
    Others can add your repository to their local clone of KBibTeX's git and clone your branch (assuming in this example it is located on KDE's Git server):


        git remote add someonespublicclone [email protected]:clones/kbibtex/NAME/kbibtex # run once
    <!--T:52-->
        git fetch someonespublicclone feature/xxxx && git checkout feature/xxxx # every time to get updates
    {{Input|git remote add someonespublicclone [email protected]:clones/kbibtex/NAME/kbibtex # run once
        git remote rm someonespublicclone && git checkout master && git branch -D feature/xxxx # to erase branch
    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}}


    === Create Release Branches and Tags ===
    === Create Release Branches and Tags === <!--T:53-->


    <!--T:54-->
    To create a release branch from {{path|master}} and push it to {{path|origin}}, run
    To create a release branch from {{path|master}} and push it to {{path|origin}}, run


        git checkout -b kbibtex/0.6 master && git push origin kbibtex/0.6
    <!--T:55-->
    {{Input|git checkout -b kbibtex/0.6 master && git push origin kbibtex/0.6}}


    <!--T:56-->
    To tag a release in a release branch, run the following commands:
    To tag a release in a release branch, run the following commands:


        git checkout kbibtex/0.6 # be in right branch
    <!--T:57-->
        git pull --ff-only # get latest changes from origin
    {{Input|git checkout kbibtex/0.6 # be in right branch
        git status # just check that everything is ok
    git pull --ff-only # get latest changes from origin
        git tag -s -u GPGKEY -m "Tagging 0.6" v0.6 # actual tagging, GnuPG signed
    git status # just check that everything is ok
        git push --tags # explicitly push tag to origin
    git tag -s -u GPGKEY -m "Tagging 0.6" v0.6 # actual tagging, GnuPG signed
    git push --tags # explicitly push tag to origin}}


    == Creating a Release ==
    == Creating a Release == <!--T:58-->


    <!--T:59-->
    {{Info|This section describes how to create releases based on KDE4 (kdelibs4). It will not work for KDE Frameworks 5.}}
    {{Info|This section describes how to create releases based on KDE4 (kdelibs4). It will not work for KDE Frameworks 5.}}
    To create a release, use the Ruby scripts from the {{path|git.kde.org:releaseme.git}} repository. KBibTeX's package generation is configured through files {{path|kbibtex.rb}} and {{path|kbibtexrc}}. Configure those files or invoke {{path|kbibtex.rb}} with the correct arguments, such as:
    To create a release, use the Ruby scripts from the {{path|git.kde.org:releaseme.git}} repository. KBibTeX's package generation is configured through files {{path|kbibtex.rb}} and {{path|kbibtexrc}}. Configure those files or invoke {{path|kbibtex.rb}} with the correct arguments, such as:


        ./kbibtex.rb --src=file:///${HOME}/git/kbibtex --version=0.6.0 --no-doc --no-l10n
    <!--T:60-->
    {{Input|1=./kbibtex.rb --src=file:///${HOME}/git/kbibtex --version=0.6.0 --no-doc --no-l10n}}


    <!--T:61-->
    Fetching documentation and translation files is the most time-consuming part of this process.
    Fetching documentation and translation files is the most time-consuming part of this process.


    <!--T:62-->
    Detached cryptographic hashes can be created and signed like this:
    Detached cryptographic hashes can be created and signed like this:


        sha512sum kbibtex-0.6.0.tar.xz >kbibtex-0.6.0.tar.xz.sha512
    <!--T:63-->
        gpg --default-key GPGKEY --output kbibtex-0.6.0.tar.xz.sha512.asc --detach-sign --armor kbibtex-0.6.0.tar.xz.sha512
    {{Input|1=sha512sum kbibtex-0.6.0.tar.xz >kbibtex-0.6.0.tar.xz.sha512
        gpg --default-key GPGKEY --output kbibtex-0.6.0.tar.xz.asc --detach-sign --armor kbibtex-0.6.0.tar.xz
    gpg --default-key GPGKEY --output kbibtex-0.6.0.tar.xz.sha512.asc --detach-sign --armor kbibtex-0.6.0.tar.xz.sha512
    gpg --default-key GPGKEY --output kbibtex-0.6.0.tar.xz.asc --detach-sign --armor kbibtex-0.6.0.tar.xz}}
     
    </translate>

    Revision as of 09:17, 18 November 2018

    Other languages:

    Various Useful Resources

    The following links refer to other web pages or resources relevant for the development of KBibTeX.

    Quick Start to Run KBibTeX from Git

    A quick and easy method to fetch, compile, and run KBibTeX from Git, i.e. the lastest code from master branch, is to get the run-kbibtex.sh Bash script from Thomas Fischer's 'KBibTeX-related' Git repository.

    To run the script, either make it executable and run it via

    ./run-kbibtex.sh

    or invoke it via

    bash run-kbibtex.sh

    The script will by default clone KBibTeX's Git repository into a temporary directory, compile it, install it in a temporary directory, and launch this temporary installation of KBibTeX.

    The script does not need to be run as root or with sudo. It will not make any permanent modifications on your system. In order to compile KBibTeX, various tools and development libraries must be available beforehand, e.g. installed via the distribution's package management system.

    There is a README.txt file explaining the script in greater detail.

    Getting the Source Code

    KBibTeX's sources are 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 KDE's Git server.

    Branches

    Main development happens 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 something like 0.6. Actual releases are tagged commits ('tags') within such a branch, for example v0.5.1. There won't be branches for bug fix releases, e.g. no kbibtex/0.6.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 (typical for features) or a release branch (typical for bugs). Branches for bugs are meant to be merged into the release branch where the bug was reported for as well as into the master branch (for future releases). Feature branches are merged into the master branch, in selected cases into releases branches where no release has been tagged yet, and only in rare cases back-ported to release branches with published releases. An example for a feature branch would be feature/zotero, which may contain the code for an improved Zotero support. Names for bug report-related branches are bugs/bugsystemnumber (for example bugs/kde338375) , where bugsystem would be kde or the name of a Linux distribution and number the actual bug number. Feature branches start with feature/ followed by a short descriptive name for this feature (all lowercase, no spaces). Merged branches will be delete after some time.

    Compiling the Code

    The following instructions provide information how to compile KBibTeX on the command line. Instructions are similar but differ slightly between KDE4-based builds (e.g. branch kbibtex/0.5) and KDE Frameworks 5-based builds (e.g. branch master). When compiling KBibTeX from inside of an IDE like KDevelop or Qt Creator, those settings have to be applied as well.

    Running CMake

    KBibTeX is configured using CMake. There are a few options relevant for the configuration of this project:

    1. CMAKE_INSTALL_PREFIX:PATH specifies the installation location. There are a number of choices available for this option:
      1. The location of your KDE installation, for example /usr. The commands kde4-config --prefix (compiling for KDE4) or kf5-config --prefix (compiling for KDE Frameworks 5) print this location. Picking this option most likely will require root permissions (e. g. via sudo) for the actual installation. Caution: This choice will interfere with the package management.
      2. A directory outside the package management's control, for example /usr/local. Requires setting some environment variables as explained below. This installation stays available across reboots and is available to all users. Picking this option most likely will require root permissions (e. g. via sudo) for the actual installation.
      3. A user-writable directory like /tmp/usr or ~/usr. Similar to above choice, it requires setting some environment variables, but no root permissions. Many distributions are configured to clean /tmp on reboot.
    2. CMAKE_BUILD_TYPE determines 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 debugfull works 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

    Compiling

    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 -j$(nproc)

    To make use 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

    Installation

    KBibTeX uses KDE'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. Depending on your choice of installation prefix, this statement has to be run with sudo or alike.

    Unless the installation prefix equals the KDE install directory, the following environment variables have to be specified. You may set the variables temporarily in an active shell session, permanently setting them in your shell's configuration, or create a small shell script that both sets those variables and then launches your custom KBibTeX installation.

    1. Only for KDE4: Set variable KDEDIRS to include the KDE installation directory and KBibTeX's installation directory, for example /usr:/tmp/usr
    2. Only for KF5: Set variable QT_PLUGIN_PATH to include the plugin directory inside the library directory of KBibTeX's installation directory, for example /usr/lib/plugins:/usr/lib/qt5/plugins:/tmp/usr/lib64/plugins/
    3. Set variable LD_LIBRARY_PATH to the library directory inside KBibTeX's installation directory, for example /tmp/usr/lib64
    4. Set variable XDG_DATA_DIRS to 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

    Run kbuildsycoca4 (KDE4) or kbuildsycoca5 (KDE Frameworks 5) to make the KDE subsystem aware of the new libraries.

    Attention

    KBibTeX consists of the actual program and a number of libraries. To avoid undefined behavior, it is important to uninstall any other KBibTeX installations (e.g. those done via the Linux distribution's package management system) and to remove any remaining KBibTeX libraries (e.g. those files found anywhere under /usr) that match the pattern *kbibtex*.so*.


    Now KBibTeX can be started, like shown in this example:

    /tmp/usr/bin/kbibtex

    Git cookbook

    A number of pages in TechBase, UserBase, and Community discuss using Git for source code management. This section shows some examples how Git is used for KBibTeX.

    Create a Feature or Bug Branch

    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. Bugs in other bug trackers such as Gna! or your distribution may use a different prefix such as bugs/gnaNNNN or bugs/gentooNNNN.

    git branch --track feature/xxxx origin/master && git checkout feature/xxxx

    Pushing a Local Feature or Bug Branch

    To minimize polluting the official KBibTeX repository or when you do not have 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 (assuming in this example it is located on KDE's Git server):

    git remote add someonespublicclone [email protected]: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

    Create Release Branches and Tags

    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

    Creating a Release

    Information

    This section describes how to create releases based on KDE4 (kdelibs4). It will not work for KDE Frameworks 5.

    To create a release, use the Ruby scripts from the git.kde.org:releaseme.git repository. KBibTeX's package generation is configured through files kbibtex.rb and kbibtexrc. Configure those files or invoke kbibtex.rb with the correct arguments, such as:

    ./kbibtex.rb --src=file:///${HOME}/git/kbibtex --version=0.6.0 --no-doc --no-l10n

    Fetching documentation and translation files is the most time-consuming part of this process.

    Detached cryptographic hashes can be created and signed like this:

    sha512sum kbibtex-0.6.0.tar.xz >kbibtex-0.6.0.tar.xz.sha512
    gpg --default-key GPGKEY --output kbibtex-0.6.0.tar.xz.sha512.asc --detach-sign --armor kbibtex-0.6.0.tar.xz.sha512
    gpg --default-key GPGKEY --output kbibtex-0.6.0.tar.xz.asc --detach-sign --armor kbibtex-0.6.0.tar.xz