Skip to content

Development: Getting Started

Jump to bottom
Matt Young edited this page May 25, 2024 · 28 revisions

These notes are written on the assumption that you're developing on Linux. Developing on Windows or Mac should be pretty similar, but a few of the details might differ slightly. See Building on Windows -- Prerequisites for one way to get set up on Windows.

Prerequisites

To build Brewken, you will initially need:

  • a mainstream C++ compiler (in particular for which cmake can generate project files or makefiles) such as g++ or clang++
  • Python version 3.10 or newer (for some of the build and packaging scripts).
  • Pip (also for some of the build and packaging scripts)
  • Git
  • On Windows you also need:
  • On Mac, you also need:

Automatically installing other dependencies

Once you have your C++ compiler, Python, Pip and Git, you can install other dependencies automatically with a script. Of course, first you need to get the script and the rest of the Brewken source code. Look ahead to the section Getting set up on GitHub and Git to get the code. Then, inside the brewken directory, run the following:

./bt setup all

On Linux, the script will ask for your password in order to execute sudo apt install.

Manually installing other dependencies

If you prefer, then, instead of running ./bt setup all, you can install the dependencies manually. You'll need:

On Debian systems like Ubuntu, you can install all the above (except Boost -- see below) by installing the following packages (with sudo apt install or similar):

  • meson
  • cmake
  • doxygen
  • git
  • libqt5multimedia5-plugins
  • libqt5sql5-psql
  • libqt5sql5-sqlite
  • libqt5svg5
  • libqt5svg5-dev
  • libxalan-c-dev
  • libxalan-c-doc
  • libxerces-c-dev
  • libxerces-c-doc
  • qtbase5-dev
  • qtmultimedia5-dev
  • qttools5-dev
  • qttools5-dev-tools

If you want to build the install packages (rather than just install locally with make install), you'll also need:

  • debhelper to build .deb packages for Debian/Ubuntu
  • lintian to validate .deb packages
  • rpm to build RPMs
  • rpmlint to validate RPMs

(The following are no longer needed, though you may see reference to them in old comments: qt5-default, libqt5webkit5-dev)

We need a recent version of Boost, ie Boost 1.82 or newer, to use Boost.JSON. For Windows and Mac this is fine if you are installing from MSYS2 or Homebrew respectively. Unfortunately, as of late-2022, many Linux distros provide only older versions of Boost (eg, Ubuntu 20.04.3 LTS offers Boost 1.71, as can be seen by running dpkg -s libboost-dev | grep 'Version').

To manually install the latest version of Boost from source, first uninstall any old version installed via your distro (eg, on Ubuntu, this means sudo apt remove libboost-all-dev), then follow the instructions at boost.org. It's best to leave the default install location: headers in the boost subdirectory /usr/local/include and libraries in /usr/local/lib. (It might initially seem a good idea to put things in the same place as the distro packages, ie running ./bootstrap.sh --prefix=/usr to put headers in /usr/include and libraries in /usr/lib. However, this will mean that Meson cannot find the manually-installed Boost, even though it can find distro-installed Boost in this location.) Eg, for Boost 1.80 on Linux, this means the following:

$ cd ~
$ mkdir ~/boost-tmp
$ cd ~/boost-tmp
$ wget https://boostorg.jfrog.io/artifactory/main/release/1.80.0/source/boost_1_80_0.tar.bz2
$ tar --bzip2 -xf boost_1_80_0.tar.bz2
$ cd boost_1_80_0
$ ./bootstrap.sh
$ sudo ./b2 install
$ cd ~
$ sudo rm -rf ~/boost-tmp

Getting set up on GitHub and Git

A small aside: you may already know that Git automatically adds your name and email address to commits. If it's been a while since you set Git up on your machine, you can check it's using the right version of your name and the right email address via:

$ git config --global user.email
$ git config --global user.name

If you have not used git much before, it is well worth reading Understanding Git Conceptually. It is a concise and well-written document about how git operates.

The first thing to do is create a fork of the brewken project, so you've got your own dev area on GitHub. Once you've done this then you'll have a page https://github.com/yourusername/brewken (but with yourusername replaced by your username).

Now get things set up on your local machine:

$ git clone https://github.com/yourusername/brewken
$ cd brewken
$ ./setupgit.sh
$ cd .git
$ cat << EOF >> config
> [alias]
>    lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative
> EOF
$ cd ..
$ git remote add upstream http://github.com/Brewken/brewken.git
$ git fetch upstream
$ git submodule update --init --recursive

There is now a fork in the road. The old tried-and-tested build system uses CMake and a couple of helper shell scripts. The new not-yet-100%-finished build system uses Meson and Python scripts.

Old Build System

Run the following:

$ ./configure

Note that this command (./configure) creates the build subdirectory and does a bunch of initialisation in it so that, once you're in that build directory, you can build/install/test/etc with make. On Windows the ./configure script still needs some work. So, instead, enter the following commands from the MinGW Mintty shell:

$ mkdir build
$ cd build
$ cmake .. -DCMAKE_RC_COMPILER:FILEPATH=windres.exe -G "MSYS Makefiles"

New Build System

Run the following (skipping the first line if you did it already above) from the brewken directory:

$ ./bt setup all
$ cd mbuild
$ meson compile

Working on the code

Brewken aims to follow the standard git branching model. To fix a but or add a feature to brewken, you'll create a fork of its repository into your own private repository. Then, create exactly one branch per feature you want to add. It will be merged back to the brewken repository using pull requests.

Specifically, to add make a new branch and start working on it, use the following commands (replacing 'myAmazingFeature' with something appropriate):

$ git branch myAmazingFeature upstream/develop
$ git checkout myAmazingFeature

To locally check in your work:

$ git commit -am 'Added new class AmazingFeature to implement etc'

This won't pick up new files, unless you already told git to add them, eg:

$ git add src/WhateverTheNewFileIsCalled

Or if you added several new files, this will add all files newly created since the branch:

$ git add --all

But, NB, this can sometimes add things you don’t want. Check with the command below then, before committing, remove anything you didn’t want to add, eg:

$ git reset src/FileIDidNotWantToAdd

To see which files you have changed in the branch you are working on:

$ git diff --name-only upstream/develop

But if you have also added new files, the following command is a better check that you remembered to do git add on them:

$ git status

To see how much changed in each file in the branch you are working on:

$ git diff -w --stat upstream/develop

To see what branches exist, and what the currently checked-out one is:

$ git branch

To see what changed in a given file since the branch was created:

$ git diff -w upstream/develop -- ../src/TheFileIAmInterestedIn

(The -w option ignores all whitespace.)

To see in summary recent commits in the git tree:

$ git reflog

To see in detail recent commits in the git tree:

$ git log

To merge all oustanding changes in from the main project development branch:

$ git fetch
$ git merge upstream/develop

Or you can combine the two commands as follows:

$ git pull

This also does a commit (which you can see with git show), so you don’t need a separate commit afterwards. However, don’t forget to run make again after doing such a merge! See more details at https://stackoverflow.com/questions/21756614/difference-between-git-merge-origin-master-and-git-pull. NB: If there are conflicts, you need to edit the files to resolve them. If you lose track of which files still have conflicts, type:

$ git status

Once you have resolved the conflicts in a file (by searching for <<<< or >>>> and editing), you do:

$ git add ../src/WhateverTheFileIs.cpp

Then, once all conficts resolved:

$ git commit -am 'Resolve conflicts from upstream/develop merge'

Finally, when you’re ready to submit (obviously change myAmazingFeature to your actual branch name, and remember to have your GitHub credentials handy):

$ git push origin myAmazingFeature

This will also give you a browser link to create a pull request. If you then need to make further changes, you can repeat the last two steps and your edits should automatically show up in your pull request.

Once your pull request is accepted and merged you can delete your local branch:

$ git branch -D myAmazingFeature

Next: Development: Building

Clone this wiki locally