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.freenode.net.
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

• Install the KDevelop IDE (Integrated Development Environment). You should use your distribution's package, or build using Konstruct.
• Fire up KDevelop and from the "Project" menu, select "Open Project...", then choose the amarok.kdevelop file from the extragear/multimedia/amarok/ directory.
• Compile Amarok normally once through the standard means.
• From the "Build" menu select "Build Project" to build Amarok after you have made changes.
• To find the source of a particular feature, a good method is to find an English string associated with the feature and then search for it via "Edit" → "Find in Files".
• For more on setting up KDevelop 4, see Setting up KDevelop
  • Note: If anyone knows how to debug Amarok in Kdevelop please add detailed instructions here.

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 QtCeator's make
  • 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
    • alas in my experience debugging this binary will confuse amarok a little (yet to work out why - specifically it throws up this error: "The amarok database reported the following errors: The configured database plugin could not be loaded. In most cases you will need to resolve these errors before Amarok will run properly." for me.)
    • If you want to debug the installed binary in $HOME/kde/bin/amarok (this does not produce the aforementioend error for me) then:
      • Beside Run Configuration blick 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.