====== Building Rosegarden from Source ======


===== Get the Source =====

There are three main ways to get the source:

  * Download a release tar file.  If you only need one of the stable releases.
  * Download a source snapshot.  If you need something more recent than the last release or you need a version with a specific change.  It may not be 100% stable, but it should be ok.
  * Use git.  If you want the latest and you want to follow along as changes are made.

Instructions for each of these approaches follows...

==== Release tar File ====

Release tar files for each release can be found here:

https://sourceforge.net/projects/rosegarden/files/rosegarden/

Download one of those, expand it, and switch into the directory it creates.  E.g. for 20.12:

  tar -xf rosegarden-20.12.tar.bz2
  cd rosegarden-20.12

==== Source Snapshot ====

From Rosegarden's "Code (git)" page:

https://sourceforge.net/p/rosegarden/git/ci/master/tree/

...click on the "Download Snapshot" link.  Then save that zip file someplace.  It will have a very large name.  Use the unzip command to unzip that zip file and switch into its directory:

  unzip rosegarden-git-da13598927a3adfdf85880fcdf95cf0d06ebf8f1.zip
  cd rosegarden-git-da13598927a3adfdf85880fcdf95cf0d06ebf8f1

Note that you do not have to type all of that.  bash offers filename completion with the tab key.  So all you need to do is type the beginning of the name, press tab, and bash will complete the filename for you.  As an example, type this and press the tab key:

  unzip rose

Unless you have several zip files downloaded, that should fill out the rest of the name.  This works for the cd command as well.

==== Using git ====

Follow the steps on the [[dev:Using git]] page to get a copy of the Rosegarden source code with git.

===== Get Dependencies =====

Follow the steps on the [[dev:Get Dependencies]] page to make sure you have the needed dependencies.

===== Development Configuration =====

==== Core Dumps ====

Core dumps can be quite handy when debugging, but generally these are turned off to avoid wasting disk space.  To turn them back on, edit ''/etc/security/limits.conf'' and add these lines:

<file>
*               hard    core            unlimited
*               soft    core            unlimited
</file>

Also check the kernel's "core_pattern" setting:

<code bash>
$ cat /proc/sys/kernel/core_pattern
core
</code>

If you see something other than "core", it's likely that you will not see core dumps.  To solve this problem you will likely have to disable whichever program is setting core_pattern.  E.g. for apport, go to /etc/default/apport and set enabled to 0.

Reboot your machine and core dumps should be enabled.  Confirm with the ''ulimit'' command:

<code bash>
$ ulimit -c
unlimited
</code>

Much more info can be found in the man page for **core**(5).
==== Multithreaded make ====

If you have a machine with multiple cores (who doesn't these days?) you probably want to add this to the end of your .bashrc file to tell make that it can run multiple jobs simultaneously:

  export MAKEFLAGS="-j `nproc`"
  
This will take effect the next time you start a terminal.  It should speed up the build significantly.

==== QT_FATAL_WARNINGS ====

//You can skip this section.//

Back when we were using Qt4 and the compiler couldn't check signals and slots, I found turning on QT_FATAL_WARNINGS to be very helpful when debugging signal and slot issues.  Nowadays, not so much.  Here's the info in case it comes in handy in the future...  To turn on QT_FATAL_WARNINGS, add this to your .bashrc file:

  export QT_FATAL_WARNINGS=1

This will make sure any Qt warnings stop the run so you will notice them and fix them.  This is really helpful when working with old-style (Qt4) signals and slots since the compiler has no idea whether the names of signals and slots actually exist.  Downside: there is a slight chance that this will cause Qt apps (built in debug mode) to crash when run from the command line.  //[In Ubuntu 20.04 I'm getting harmless Xcb warnings in the Matrix editor that cause Rosegarden to crash.  Removing QT_FATAL_WARNINGS for now.  Retest at the next Ubuntu LTS release.]//

===== Build and Run =====

See the README for the complete build instructions.  Here's a summary...

Switch into your rosegarden source directory.  You should see something like this when you do an ''ls'':

  $ ls
  AUTHORS    cmake           COPYING   README              scripts    test
  build      CMakeLists.txt  data      README.DEVELOPERS   src
  CHANGELOG  CONTRIBUTING    Doxyfile  rosegarden.spec.in  templates

Create a build directory, and switch into that.

  mkdir build
  cd build

Run cmake to generate a make file.

  cmake .. -DCMAKE_BUILD_TYPE=Debug

There may be errors when you run cmake due to missing dependencies.  You'll need to track those down and re-run cmake.  (See the [[dev:Get Dependencies]] page for details.)

Once cmake has run successfully to completion, you can build Rosegarden with make:

  make

To make sure the build was successful, try running it:

  ./rosegarden

===== References =====

Information in this page was pulled from current and older versions of the following pages:

  * [[dev:Contributing]]
  * [[dev:Eclipse]]
  * [[:Development from svn]]
  * [[:Stable from svn]]