Amarok/Development/Hacking On Amarok HowTo

How to become involved

1. Most discussion regarding Amarok development happens in IRC. Join us in #amarok on irc.libera.chat.
2. Join the mailing list.
3. Read everything in the HACKING folder. It goes over the Amarok coding style and other important information.
4. Submit your patch. There are several channels to do so:

• Bug Tracker: Search for the problem you are solving on KDE's bugzilla and attach the patch. If there isn't a bug for it yet, create a new bug or wishlist and then attach the patch.
• IRC: IRC has the advantage that a developer might happen to be online and has the time to test your patch, it could be applied immediately or give immediate feedback.
• Mailing lists: Things often get overlooked in the mailing list, so do not rely on it. However it is a good method of bringing up a subject with the development team.

How to Hack on Amarok's Codebase Using KDevelop

• Build Amarok once through the CLI by following: Amarok/Development/Development HowTo
  • This is a very important step. If you can't build it that way, you won't find much joy with an IDE.
  • It will also ask you to run cmake with appropriate settings that build a CMakeCache.txt
• Install the KDevelop IDE (Integrated Development Environment). You should use your distribution's package, or build using Konstruct.
• Start KDevelop and open the project:
  • click Open/Import Project... on the Project menu
  • Choose the amarok.kdev4 (in the $HOME/kde/src/amarok if you followed Amarok/Development/Development HowTo)
  • Click Finish
  • You'll now see amarok in the Project pane on left.
• Configure the project
  • click amarok in the Project pane on left.
  • click Open Configuration... on the Project menu
  • Under Configure CMake settings notice that there is an unlabelled build directory selector.
    • This is where we need to ensure the build directory is configured to $HOME/kde/build/amarok as per Amarok/Development/Development HowTo)
    • If it's not set to that, click + which will display a configuration dialog box, in this box
      • set the Build Directory to $HOME/kde/build/amarok
      • Set the Installation Prefix to $HOME/kde
      • Set the Build type to Debug
      • Click OK
    • Once it is set right notice the Cache Values and check that:
      • CMAKE_INSTALL_PREFIX = $HOME/kde
      • CMAKE_BUILD_TYPE = Debug
    • Now click Make on the selector at left to see the make settings
    • Under Number of simultaneous jobs enter 16 (or if not 16 as many parallel jobs as you'd like make to run, I've just used twice the number of cores I have following some advice but can't really comment on what's optimum here, I use an 8 core processor with 32GB RAM and an SSD and a full rebuild was taking 15 mins, but I got that down to 3 mins with this one tweak).
    • Under Default make target type install (that will just ensure when you build it'll but binaries in your $HOME/kde/bin folder as well)
    • Click OK
  • Build the project
    • Select amarok in the Project pane, and click the Build Selection button or Build Selection on the Project menu or press F8
  • Check your file system and content yourself that the binaries appeared where you expect them with last modified times of about now, i.e. you just built them.
    • There should be an amarok binary in $HOME/kde/build/amarok/src
    • There should be an amarok binary in $HOME/kde/bin
    • If not content they were built, remove them and build again to see that they were built
• This intro is not complete:
  • For more on setting up KDevelop 4, see Setting up KDevelop
  • We need to introduce how to debug in amarok in Kdevelop

How to Hack on Amarok's Codebase Using Qt Creator

• Build Amarok once through the CLI by following: Amarok/Development/Development HowTo
  • This is a very important step. If you can't build it that way, you won't find much joy with an IDE.
  • It will also ask you to run cmake with appropriate settings that build a CMakeCache.txt
    • Most importantly this file contains the definition of the install directory which will be useful below.
• Fire up Qt Creator, and from the "File" menu select "Open File or Project".
• Navigate to the Amarok source directory and select the file CMakeLists.txt
  • NOTE: If Qt Creator opens CMakeLists.txt as a text file and doesn't start the CMake Wizard, you may have to install a separate CMake plugin for QtCreator (the build available in the Ubuntu repositories itemizes it out as 'qtcreator-plugin-cmake').
  • The Configure Project page is displayed. On this page, under Default make sure to enter $HOME/kde/build/amarok then click Configure Project
• Configure QtCreators Cmake settings
  • If you followed these instructs so far, then CMake was run with the command line options:
    • -DCMAKE_INSTALL_PREFIX=$HOME/kde -DCMAKE_BUILD_TYPE=debugfull
  • These are stored in your build directory in the file CMakeCache.txt now. And you can build happily from here on in.
  • But if you ever want to run Cmake from within QtCreator some time you should configure that here:
    • Under Build Settings find Build Steps, and under that find CMake.
    • Check that the Build directory is right. If you've followed steps this far it should read $HOME/kde/build/amarok (with $HOME expanded)
    • Enter the CMake arguments as -DCMAKE_INSTALL_PREFIX=$HOME/kde -DCMAKE_BUILD_TYPE=debugfull
      • BUT don't type $HOME, expand it to your home directory explicitly. Environment variables won't be substituted when CMake is run and if you leave $HOME there when QtCreator runs CMake it will create a directory called $HOME literally in you build directory.
    • Now run CMake again:
      • On the Build menu click Run CMake
• Configure QtCeator's make settings
  • Implement paralellism
    • If you have a multicore processor the default build time may be a lot slower than need be. I use an 8 core processor with 32GB RAM and an SSD and a full rebuild was taking 15 mins, but I got that down to 3 mins as follows:
    • In QtCreator, On the Mode selector, click Projects
    • Under Build Settings find Build Steps, and under that find Make.
    • Click Details
    • Under Additional arguments enter -j16 (or if not 16 as many parallel jobs as you'd like make to run, I've just used twice the number of cores I have following some advice but can't really comment on what's optimum here).
  • Ensure that the builds are installed
    • You will have executed make install and tested the result already (step 1 above)
    • make install put the binaries in $HOME/kde/bin
    • QtCreator doesn't know to do that by default and will build them in your build directory ($HOME/kde/build/amarok if you got this far).
    • To help QtCreator out,
      • In QtCreator, On the Mode selector, click Projects
      • Under Build Settings find Build Steps, and under that find Make.
      • Click Details
      • Under Targets' click install
    • Now QtCreator will deploy the built binaries to $HOME/kde/bin
• Configure what to run
  • By default testamarok will be configured to run. You can run this once if you like, it's a good test after all. To do so, just click Run button on the Mode selector or press CTRL+R or click Run on the Build menu.
  • To run amarok proper and check your hacks: under Run configuration
    • select amarok if you want to use the make target "amarok". This will be in $HOME/kde/build/amarok/src and maybe add --debug to Arguments
    • If for any reason you want to debug the installed binary in $HOME/kde/bin/amarok then:
      • Beside Run Configuration click Add and select Custom Executable
      • Under Executable and Working directory enter $HOME/kde/bin/amarok
      • Maybe add --debug to Arguments
• Build and run amarok
  • Click Run button on the Mode selector or press CTRL+R or click Run on the Build menu.
  • If you have any problems, first try running "kbuildsycoca4 --noincremental" from a terminal, and try again. That should tidy up any KDE config issues which might cause Amarok some grief.
• Try debugging
  • Click Edit on the Mode selector
  • Open src/main.cpp in the project tree
  • Set a breakpoint somewhere in int main( int argc, char *argv[] ), by clicking in the far left margin of the editor to left of the line number. A red dot should appear indicating a break point.
  • Click Start Debugging' button on the Mode selector or press F5 or click Start Debugging on the Debug menu.
  • Amarok should be built and run and the editor will stop at your breakpoint.
  • Now you can get familiar with all the tools for inspecting local data, and single stepping the code. Happy hacking.