You can easily make changes to your local copy of the SKIRT source tree using any text editor, and rebuild the code using the procedures described elsewhere in this installation guide. Once you get into substantial development work, however, and especially if you plan to contribute code back to the main SKIRT repository, it becomes beneficial to use Qt Creator as an integrated development environment, and to follow the procedures outlined below.

Note: The description below assumes that you successfully completed the installation instructions provided by the topic Install SKIRT using Qt Creator (all platforms) and any references therein.

This advanced topic contains the following sections:

Install the source code formatter (optional)

If you plan on writing or updating SKIRT source code, you may wish to install clang-format, the tool used to automatically format all C++ source code in the SKIRT repository, as described in this section. The clang-format tool is part of the open source LLVM Clang C/C++ compiler effort.

Currently, the SKIRT repository requires clang-format version 18.1.x, where x stands for any subversion. It is important to install this same version because the various (major) versions of the tool tend to format the source code somewhat differently, even with the same option settings.

For information on how to use the source code formatter, see Formatting the source code.

MacOS

Recent versions of the Xcode development environment include an Apple-specific version of clang-format. Unfortunately, this version is not fully lined up with an official LLVM version, so it cannot be used for our purposes.

The best option is to install the complete Clang distribution, which includes clang-format. Information can be found at the LLVM download page: https://releases.llvm.org/download.html. Look for a pre-built binary package of the correct clang-format version that is also appropriate for your operating system version and hardware. However, it seems that the required combination is often not available.

Another option is to build Clang from source code using an install tool such as port or brew.

Once installed, you need to add the path to the clang-format executable to your PATH environment variable. For example, after building and installing clang-18 with the port install tool, adding the following line to the login script does the trick:

export PATH="/opt/local/libexec/llvm-18/bin:$PATH"

Other systems

On Ubuntu 24.04 systems, clang-format version 18.1 can be installed by entering:

sudo apt install clang-format

or perhaps

sudo apt-get install clang-format-18

On other systems, the package manager might offer similar capabilities. Otherwise, refer to the installation instructions on the Clang LLVM web site. One option is to install the pre-built binaries of the complete Clang distribution for the appropriate operating system, which can be obtained from the LLVM download page: http://releases.llvm.org/download.html.

Build the documentation formatter (optional)

If you plan on writing or updating the documentation in the SKIRT code, you may wish to build doxstyle, a tool to assist with formatting /**-style documentation blocks in .hpp header files. The doxstyle tool is included as part of the SKIRT code tree and can be enabled through a build option.

To build the doxstyle tool, turn on the "BUILD_DOX_STYLE" build option and rebuild the SKIRT project. For information about build options, see Use the SKIRT build options (all platforms). For instructions on how to configure build options, see Configure and build the code.

For information on how to use the documentation formatter, see Formatting the source code.

Install the documentation generator (optional)

The reference documentation for the SKIRT code is generated from the source code files by the freely available application Doxygen, which uses the dot tool (part of the Graphviz graph visualization software) to generate diagrams. Most SKIRT users and developers do not need to (re-)generate the documentation. However, if you wish to verify that the formatting instructions and formulae in your source code comments are properly rendered in the final documentation, you can install the appropriate tools as described in this section.

For information on how to actually generate the documentation for the SKIRT code after installing these tools, see Generating the SKIRT project documentation.

Version info

The documentation on this web site has been generated with Doxygen version 1.9.5 and dot - graphviz version 2.36.0 on macOS 12.6 (Monterey). Earlier versions of these tools might not support all options and commands used in the documentation.

MacOS

Installing Doxygen

Navigate to the Doxygen download page.
Scroll down and download the most recent binary distribution for macOS.
After the download completes, open the '.dmg' file to mount the Doxygen installation disk.
In the Finder window that appears, drag Doxygen.app into your applications folder.

Installing the Graphviz Graph Visualization Software

Navigate to the Graphviz download page.
Follow the instructions on that web page.

Ubuntu

On Ubuntu a version of Doxygen including the Graphviz tools can be installed by entering:

sudo apt-get install doxygen

Other systems

On other systems, the package manager might offer similar capabilities. Otherwise, refer to the installation instructions on the Doxygen and Graphviz web sites.

Configure Qt Creator for development

General preferences

Before using Qt Creator for substantial SKIRT development, you should adjust its preferences as follows. Launch Qt Creator and open the preferences panel. On the various tabs listed below, make the specified adjustments (leaving other settings untouched), and at the end press the OK button to confirm the changes.

"Text Editor -> Behavior" tab
- Tab size: 4
- Backspace indentation: Follow Previous Indents
- In entire document: On
- Default encoding: UTF-8
- UTF-8 BOM: Always Delete
"Text Editor -> Display" tab
- Display right margin at column: 120
- Highlight current line: On
"C++ -> Code Style" tab
- press the "Import..." button, select the file ~/SKIRT/git/Docs/templates/SkirtCodeStyle.xml and press the "Open" button
"C++ -> File Naming" tab
- Header suffix: hpp
- Lower case filenames: Off
- License template: press the "Choose..." button, select the file ~/SKIRT/git/Docs/templates/LicenseTemplate.txt and press the "Open" button
"Build & Run -> General" tab
- Save all files before build: On
"Build & Run -> Default Build Properties" tab
- Default build directory: "../%{BuildConfig:Name}"
"Build & Run -> Application Output" tab
- Clear old output on a new run: On
- Merge stderr and stdout: On
"Build & Run -> Compile Output" tab
- Open pane when building: On

The source code and documentation formatters

If you installed the source code formatter and/or the documentation formatter (see sections at the top of this page), you can easily use these tools from within Qt Creator after performing the additional configuration steps described in this section. For information on how to use actually use these formatters, see Formatting the source code.

Launch Qt Creator, open the preferences panel, and make the adjustments on the various tabs as listed below. Press the OK button at the end to confirm the changes.

"Environment -> External Tools" tab
- Add a new category called "Formatting"
- Add a new item called "Format C++ code in file" to this category
- Configure the attributes for this item as follows:
  - Description: "Formats the C++ code in the complete file"
  - Executable: path to the clang-format executable, for example: /opt/local/libexec/llvm-18/bin/clang-format
  - Arguments: "-style=file -i %{CurrentDocument:FilePath}"
  - Working directory: empty
  - Output: Show in pane
  - Error output: Show in pane
  - Modifies current document: on
  - Input: empty
- Add another item called "Format comments in selection" to the same category
- Configure the attributes for this item as follows:
  - Description: "Formats the doxygen blocks in the selection"
  - Executable: path to the DoxStyle executable: ~/SKIRT/release/Docs/doxstyle/doxstyle
  - Arguments: empty
  - Working directory: empty
  - Output: Replace Selection
  - Error output: Ignore
  - Modifies current document: off
  - Input: "%{CurrentDocument:Selection}"
"Environment -> Keyboard" tab
- In the long item list, select "Tools -> External.Format_C++_code_in_file"
- In the "Key sequence" field, enter the shortcut combination [Alt] + [Cmd] + [J] (on macOS) or [Alt] + [Ctrl] + [J] (on Linux)
- In the long item list, select "Tools -> External.Format_comments_in_selection"
- In the "Key sequence" field, enter the shortcut combination [Alt] + [Cmd] + [I] (on macOS) or [Alt] + [Ctrl] + [I] (on Linux)

Setup the source code repository for development purposes

If you plan to contribute code back to the main SKIRT repository, you need to prepare for using the GitHub fork and pull workflow model. Anyone can fork a repository, push changes to their personal fork, and initiate a pull request. The changes can be pulled into the original repository by a SKIRT Core Team member, possibly after discussion and/or being adjusted in one or more iterations.

To get started with contributing to one of the SKIRT project repositories:

On the GitHub web site, fork the relevant repository (see section GitHub repositories above).
Clone this personal fork to your computer, possibly replacing your direct clone of the original repository.

To initiate a pull request:

Make the desired changes, commit them, and push them to your personal fork.
Test your changes, and repeat the previous line as many times as needed.
On the GitHub web site, create a pull request from your fork.
Wait for feedback from the SKIRT Core Team.

This worklow is described in much more detail in The GitHub workflow for the SKIRT project.

For more information about contributing to the SKIRT project in general, see Contributing.