Developer guide

These notes describe how to work with, or contribute to the development version of the QWWAD source code. This is not "stable" software, and should be assumed to contain many errors - please do not this version for important simulations!!

If you wish to use the latest stable version of QWWAD, please see the guide for [Installing on Ubuntu] (recommended) or [Installing from a package].

Install dependencies

Before working with the source code, you will need to install all relevant dependencies. Please see the relevant section in the [Installing from a package] page.

Sign into Github

The latest QWWAD code is manged using a Git repository, located at https://github.com/QWWAD/qwwad

You will need to sign up for a free Github account if you don't already have one. There is an option to do this when you follow the link above.

If you haven't used Git (or Github) before, see https://help.github.com/articles/set-up-git/ and the other useful help pages in the Github guide to get set up for the first time.

Once you have signed into Github, you will need to make a local clone of the QWWAD repository. You can either do this using the "Clone or download" button on the Github website, or you can do it on the command-line in Linux/OSX. For the latter option, do something like this:

::sh
# Clone the code into a folder called "qwwad-source"
git clone https://github.com/QWWAD/qwwad qwwad-source

If you look inside that folder, you will see the latest version of the code.

Configure CMake

The latest version of QWWAD uses the CMake build system, which should (hopefully!) be simpler, and work better on Mac OSX.

You will need to install the CMake program if you don't already have it.

The first time you build the source code, you will need to create a destination folder for the build.

Assuming you're currently in the qwwad-source folder...

::sh
mkdir ../qwwad-build
cd ../qwwad-build

Now, you will now need to configure the build.

::sh
cmake ../qwwad-source

This only needs to be done the first time... you will see a number of checks being run. If any error messages appear, you will need to fix the issues before continuing! Please feel free to submit a bug report, or ask questions at https://launchpad.net/qwwad if you get stuck.

Build QWWAD

To compile and link the software, simply type:

::sh
make

On modern machines, you can use the -j option to build on multiple processes at once, which can speed things up. For example, to build in 4 simultaneous processes:

::sh
make -j4

Install QWWAD

Finally, after the programs have finished building, you can install everything to your specified installation directory using:

::sh
make install

If you chose to install it in a system folder rather than your home folder, you'll need to have root access to your machine:

::sh
sudo make install

Updating your QWWAD source code

To make sure you have the latest version of the QWWAD source code, simply go into the qwwad-source folder and pull the latest version:

::sh
git pull

If any changes have been made, you will need to go into the qwwad-build folder and run "make"/"make install" again.

Contributing to the source code

If you have been authorised as a QWWAD developer, you just need to commit any changes you make in the qwwad-source folder, and then push them to the repository:

::sh
git commit -am"A description of the changes you made"
git push

Please make sure that the code compiles correctly, and run "make check" before you do commit anything... this will help to minimise new bugs.

If you are planning to make any major changes, then please consider creating a temporary branch of the repository as described here: https://help.github.com/articles/proposing-changes-to-your-work-with-pull-requests/

If you have not been authorised as a QWWAD developer yet, we are still very keen to receive your contributions. You will need to make a "fork" of the original QWWAD repository and then submit a "pull request" as described here: https://help.github.com/articles/fork-a-repo/

The "pull request" mechanism allows us to review your changes before they become live. Once you've had a couple of contributions accepted, we may add you as an official QWWAD developer!

Note for package maintainers: [Creating releases]

[Alex Valavanis]

These notes describe how to work with, or contribute to the development version of the QWWAD source code. This is not "stable" software, and should be assumed to contain many errors - please do not this version for important simulations!!

If you wish to use the latest stable version of QWWAD, please see the guide for [installing on Ubuntu] (recommended) or [installing from a package].

Install dependencies

Before working with the source code, you will need to install all relevant dependencies. Please see the relevant section in the [Installing from a package] page.

Sign into Github

The latest QWWAD code is manged using a Git repository, located at https://github.com/QWWAD/qwwad

You will need to sign up for a free Github account if you don't already have one. There is an option to do this when you follow the link above.

If you haven't used Git (or Github) before, see https://help.github.com/articles/set-up-git/ and the other useful help pages in the Github guide to get set up for the first time.

Once you have signed into Github, you will need to make a local clone of the QWWAD repository. You can either do this using the "Clone or download" button on the Github website, or you can do it on the command-line in Linux/OSX. For the latter option, do something like this:

::sh
# Clone the code into a folder called "qwwad-source"
git clone https://github.com/QWWAD/qwwad qwwad-source

If you look inside that folder, you will see the latest version of the code.

Configure CMake

The latest version of QWWAD uses the CMake build system, which should (hopefully!) be simpler, and work better on Mac OSX.

You will need to install the CMake program if you don't already have it.

The first time you build the source code, you will need to create a destination folder for the build.

Assuming you're currently in the qwwad-source folder...

::sh
mkdir ../qwwad-build
cd ../qwwad-build

Now, you will now need to configure the build.

::sh
cmake ../qwwad-source

This only needs to be done the first time... you will see a number of checks being run. If any error messages appear, you will need to fix the issues before continuing! Please feel free to submit a bug report, or ask questions at https://launchpad.net/qwwad if you get stuck.

Build QWWAD

To compile and link the software, simply type:

::sh
make

On modern machines, you can use the -j option to build on multiple processes at once, which can speed things up. For example, to build in 4 simultaneous processes:

::sh
make -j4

Install QWWAD

Finally, after the programs have finished building, you can install everything to your specified installation directory using:

::sh
make install

If you chose to install it in a system folder rather than your home folder, you'll need to have root access to your machine:

::sh
sudo make install

Updating your QWWAD source code

To make sure you have the latest version of the QWWAD source code, simply go into the qwwad-source folder and pull the latest version:

::sh
git pull

If any changes have been made, you will need to go into the qwwad-build folder and run "make"/"make install" again.

Contributing to the source code

If you have been authorised as a QWWAD developer, you just need to commit any changes you make in the qwwad-source folder, and then push them to the repository:

::sh
git commit -am"A description of the changes you made"
git push

Please make sure that the code compiles correctly, and run "make check" before you do commit anything... this will help to minimise new bugs.

If you are planning to make any major changes, then please consider creating a temporary branch of the repository as described here: https://help.github.com/articles/proposing-changes-to-your-work-with-pull-requests/

If you have not been authorised as a QWWAD developer yet, we are still very keen to receive your contributions. You will need to make a "fork" of the original QWWAD repository and then submit a "pull request" as described here: https://help.github.com/articles/fork-a-repo/

The "pull request" mechanism allows us to review your changes before they become live. Once you've had a couple of contributions accepted, we may add you as an official QWWAD developer!