Boost.Build Plugin for Qt Creator
The idea of the Boost.Build plugin is extremely simple - use Qt Creator as a basic GUI shell to interact with the Boost.Build command.
Three main features:
- Open Boost.Build Jamfile as a project in Qt Creator.
- Build project in Qt Creator according to its configuration in Jamfile.
- Parse Boost.Build command output to enable navigation to error or warning locations.
Think of the plugin as an equivalent of Vim or Emacs with ctags and bunch of other scripts.
It turns out, that in order to achieve the three basic features above, a project manager plugin for Qt Creator needs to implement a few beefy features like: opening a project, reading project directory structure, creating nodes of project explorer tree, creating build, run, deploy configurations and corresponding build, run, deploy steps and more.
So, the Boost.Build plugin implements as little as necessary, and currently, it does not provide:
- any parsing capabilities for Boost.Build Jamfiles (not entirely true, see Features)
- any kind of GUI for updating or managing configuration stored in Jamfiles
- Tobias Hunger, Koehne Kai, Christian Kandeler, Nikolai Kosjar, André Pönitz and others for great help on the qt-creator mailing list and IRC,
- Tomasz Siekierda for writing the Building Qt Creator from Git and support through qt-creator list,
- Vladimir Prus for answering questions about Boost.Build,
- Authors of existing project manager plugins for Qt Creator - prime learning resource,
lots of thanks to!
What the Boost.Build plugin can do?
- Select a Jamfile at any level of a source tree configured with Boost.Build.
- Select files at any level of a source tree and register them as project files.
- Open Jamfile pretending it is a Qt Creator project file.
- Parse selected Jamfile to retrieve project name, if defined. Otherwise, Jamfile parent directory name is used as a project name. Finally, project name can be freely changed.
- Generate list of include paths based on configured project files tree.
- Utilise C++ browsing and editing capabilities and features of Qt Creator.
- Including the fantastic searching with the Locator
- Run Boost.Build command
b2from within Qt Creator.
- Configure Boost.Build command arguments.
- Configure Boost.Build command working directory where
- Configure Boost.Build command build directory with
- Parse Boost.Build command and Boost.Build toolset output to generate Qt Creator's
Issues list and allow navigation to file and line of error or warning.
- Currently, GCC and Clang parsers are provided.
- Configure build and clean steps.
- Configure run targets for testing and debugging.
- Save all Qt Creator project configuration changes in sidecar file
- Modify and save registered project files in sidecar file
- Modify and save includes paths in sidecar file
What the Boost.Build plugin can not do?
- Create new projects based on Boost.Build (simply, create Jamfile manually).
- Parse Jamfiles to collect list of source files which are actually used.
- Parse Jamfiles to collect configuration of targets, attributes, requirements, etc.
- Capture any project changes made in Qt Creator UI and automatically update Jamfiles.
- Change any Boost.Build configuration.
You need to build the plugin from sources.
I use Qt and Qt Creator built from sources in their Git repositories, for example:
- Qt 5 from branch: stable
- Qt Creator from branch: 3.3
So, I recommend to follow these guides:
Once you have Qt Creator build ready, you need to set two environment variables:
QTC_SOURCE- Qt Creator sources location (e.g. path to Git clone)
QTC_BUILD- Qt Creator build or install prefix where the plugin will be deployed
You can either set the variables in CLI console, if you're going to run
directly or in Qt Creator, in
settings of the
boostbuildprojectmanager.pro project, after you open it in the IDE
in order to build the plugin from Qt Creator.
- Go to Open Project and navigate to Jamfile of your project.
- Open Boost.Build Project wizard opens
- First page Project Name and Paths allows to inspect several paths and customise Project name.
- Second page Files Selection allows to generate list of files to attach to the project node in Qt Creator Projects tree and to use as input for C++ model to enable C++ navigation features for the project.
- Third page Project Management allows to add the project as a subproject, enable version control system and displays summary of auxiliary files generated by the wizard.
- Finish the wizard and let Qt Creator to generate the project tree and parse all the source files attached generating C++ model of the code.
- Go to Projects mode to inspect and customise variety of settings:
b2command working directory, that is where the command is executed
- build directory given to
b2as value of
- build steps and arguments for
b2command (e.g. change toolset, build variant)
- add custom build steps
- create run configuration with executable targets for testing and debugging
- Also, you can edit
.qtcreator.filesto add or remove source files and edit
.qtcreator.includesto specify include paths if C++ model is missing any.
For more details about individual features, steps and settings check the FAQ.
Why Boost.Build plugin for Qt Creator?
I always wanted to learn Qt programming.
When my son Hugo was born, I went on two weeks paternity leave and, somewhat inspired by the Seven by Seven idea, I decided to do an experiment: can I learn a new programming skills or work on an open source project having only a few 15-30 minutes short breaks over a day at my disposal?
Qt Creator is a fantastic and powerful IDE which is surprisingly easy and pleasent to extend.
Yet, apparently, it is much quicker to hack fairly usable Boost.Build support for Qt Creator than develop Boost.CMake and wait until it is approved by the Boost project.
Is it part of Qt Creator?
Will it become part of Qt Creator?
No demand, no man power, no plans.
UPDATE: There was an attempt to prepare contribution of this plug-in for to Qt Creator, but it failed. See the Issue #13 for details.
How does it compare to Generic Project plugin?
The Boost.Build plugin is inspired and largely based on the Generic Project plugin (aka GenericProjectManager), both idea and implementation.
The Boost.Build plugin is a hybrid between "Open Project" and "Import Project" plugin.
Similarly to Generic Project support, the Boost.Build plugin:
- allows to use Qt Creator as a code editor,
.includeskinds of auxiliary files
- allows to control some of aspects of the way project is built by modifying the build command in the Projects mode under Build Settings
- needs to be told which executable to run in in the Projects mode under Run Settings, because Qt Creator cannot automatically determine it (see TODO items)
Unlike Generic Project support, the Boost.Build plugin:
- can only use Boost.Build system and its
- relies on build configuration existing in project Jamfile files
- relies on Boost.Build project hierarchy set up by Jamroot and Jamfile files.
- allows to specify
b2working directory which can be different from both, build directory and project directory, where project directory means directory with Jamfile selected to open as a project.
- allows, thanks to previous features, to open only sub-project of a large project, for example, while working with Boost, one may use the Boost.Build plugin to compose a project which loads files only for selection of libraries, but request to run build against the whole Boost C++ libraries collection.
Finally, the Boost.Build plugin is a pilot project integrating Boost.Build system with an IDE and this experience may be useful for future improvements and development of Boost.Build system itself.
What version of Qt Creator is supported?
I use Qt Creator 3.3, but it should work with Qt Creator 3.0 or later. There are git tags corresponding to Qt Creator versions.
See also the Installation section.
How to install the plugin?
Do I need to build Qt?
I don't know. Ask Qt folks.
I follow their Getting and Building Qt Creator:
Qt Creator requires private headers of Qt, which are unfortunately not installed by the Qt binary packages
Do I need to build Qt Creator?
Apparently, yes, as per Getting and Building Qt Creator:
It is also necessary if you want to create your own Qt Creator plugin.
Have you used it on Windows?
Have you used it on Mac OS X?
What is a Jamfile?
Jamfile is a makefile of Boost.Build written in dedicated
and interpreted by Boost.Build engine which is executed and controlled by
See Boost.Build Overview
for more details.
Boost.Build convention is that the top of
is called project root where lives a Jamfile called
A project may define subprojects and each subproject is defined by a Jamfile
Jamfile in a descendant directory of the project root.
For both, root and subproject Jamfiles, Boost.Build recognises variety of file names:
[Jj]amrootas well as
[Jj]amfileas well as
Most of those names are recognised by the Boost.Build Project Manager plugin.
*.qtcreator.files file for?
Qt Creator, the Boost.Build plugin, for a Jamfile which is opened as a project,
.qtcreator.files file with list of all files selected
in the Files Selection page of the project wizard.
Role of this file is exactly the same as role of
.files file for the
It just uses different extension to clearly indicate its role and avoid file name clashes.
To add or remove files, edit the
.qtcreator.files file in Qt Creator.
(TODO: Qt Creator recreates your project tree when you save the .files file.)
*.qtcreator.includes file for?
Qt Creator, the Boost.Build plugin, for a Jamfile which is opened as a project,
This file is dedicated to specify any include paths which are solely used by Qt Creator for analysing C/C++ code of the project. Note, these include paths do not affect compilation of source files whatsoever as Jamfile files remain the only source of build configuration.
The project wizard generates initial list of include paths adding every directory of project which contains C/C++ header files. For large projects, like Boost, this may generate long list of includes paths, though it should be easy to filter it.
To add or remove include paths, edit the
.qtcreator.includes file in Qt Creator.
The paths can be either absolute or relative to the
*.user file for?
This file is natively created by Qt Creator when Opening Projects:
Qt Creator stores information that it needs to build projects in a .user file.
The Boost.Build Project Manager also uses this file to store information specific to corresponding Jamfile project, like:
- name of Jamfile project which can be customised by user in the Open Project wizard
- path of working directory used to run Boost.Build command
- path of build directory passed as value of
What is the Project Name in the Open Project wizard used for?
The Open Boost.Build Project wizard suggests project name on its first page titled Project Name and Paths.
The wizard tries to extract project name from the Boost.Build project rule, if present in the Jamfile being opened. Otherwise, the wizard uses name of parent directory of the Jamfile. Finally, user can change the Project name freely as it is only used by Qt Creator, not by Boost.Build configuration.
The idea is to provide certain degree of freedom in arranging Jamfile-based projects in Qt Creator session, regardless of their arrangements on disk.
This feature, for example, allows to generate and open multiple projects into Qt Creator and all projects may refer to the same Boost library. For instance, working with Boost.Geometry library, one may load Jamfile for tests and Jamfile for examples, selecting the same set of headers in both, and name the projects to reflect their purpose.
What is the roadmap?
None, apart form plan to roll the project forward fixing bugs and adding features as they appear useful or necessary in order to make work with Boost.Build-based a bit more accessible and efficient.
See Future section for some feature ideas.
How can I contribute?
Fork the repo and make the plugin better!
An unprioritised TODO list for the plugin:
- Add tests! Add tests! Add tests! But first, learn how to test with Qt wealth!
- Add file watchers for Jamfile and sidecar files to automatically reload any changes.
- Qt Creator recreates your project tree when you save the .files file.
- Allow to specify
b2command location not in
RunConfigurationtargets, if really needed.
- Determine toolset name from Kit and add
toolsetto additional arguments of step.
- See TODO item about
- See TODO item about
- Improve use of Qt Creator’s C++ model
for better code browsing experience
- Collect and resolve include paths as specified in all Jamfiles in project tree.
- Collect preprocessor defines from all project Jamfiles.
- Look for
user-config.jamto determine some useful settings, projects that may be referenced, include paths.
- Default toolset and use it for Kit selection/validation? See separate TODO item.
- Boost.Build Jamfile parser to enable fully-featured project management capacity by
- Parse Jamfile(s) or use b2 features if possible, to utomatically determine what executable(s) to run.
See also opened enhancement issues
at GitHub or search through the sources for
TODO, there is more items.