Qbs tutorial part 5/5: Apps

The apps

In the last part we looked at how to select files with the group feature in Qbs , and in this last part of the series we will look at how to build our apps with src/apps.qbs.

But first our file tree as a reference:

.

├── OctoMY.qbs

├── src

│   ├── agent

│   │   ├── AgentMain.cpp

│   │   ├── AgentMain.hpp

│   │   ├── app.qbs

│   │   └── README.md

│   ├── apps.qbs

│   ├── combined

│   │   └── lib.qbs

│   ├── libs

│   │   ├── libagent

│   │   │   ├── agent

│   │   │   │   ├── Agent.cpp

│   │   │   │   ├── Agent.hpp

│   │   │   │   └── AgentWindow.ui

│   │   │   ├── lib.qbs

│   │   │   └── README.md

│   ├── libs.qbs

├── test

│   ├── common_test

│   │   ├── Common_test.hpp

│   │   ├── CommsTester.cpp

│   │   ├── CommsTester.hpp

│   │   ├── mock

│   │   │   ├── MockCourier.cpp

│   │   │   └── MockCourier.hpp

│   │   ├── resources

│   │   │   ├── icons

│   │   │   │   ├── profile.svg

│   │   │   │   ├── stress.svg

│   │   │   │   └── test.svg

│   │   │   └── test_resources.qrc

│   │   ├── Utility_test.cpp

│   │   └── Utility_test.hpp

│   ├── testLogHandler

│   │   ├── TestLogHandler.cpp

│   │   ├── TestLogHandler.hpp

│   │   └── test.qbs

│   ├── testTryToggle

│   │   ├── TestTryToggle.cpp

│   │   ├── TestTryToggle.hpp

│   │   └── test.qbs

│   └── tests.qbs

└── integration

   └── qbs

     └── imports

            ├── OctoMYApp.qbs

            ├── OctoMYLibProbe.qbs

            ├── OctoMYAutoLib.qbs

            ├── OctoMYTestProbe.qbs

            ├── OctoMYAutoTest.qbs

            ├── OctoMYFiles.qbs

            ├── OctoMYQtDepends.qbs

            └── utils.js

The final part of the puzzle is our app.qbs definition which looks like this:

OctoMYApp {

    name: "Agent"

    useCombinedLibs: true

    property string path2:path

}

Again, I hope you put two and two together to realize that OctoMYApp is defined in ./integrations/qbs/OctoMYApp.qbs and represents a reusable component that is included in all our app.qbs files for centralized management for convenience.

If we follow the white rabbit again, ./integrations/qbs/OctoMYApp.qbs looks like this:

import qbs.FileInfo

Application {

    name: "OctoMYApp"

    property string appDir: FileInfo.cleanPath(path2) + FileInfo.pathSeparator()

    property string srcDir: FileInfo.cleanPath(FileInfo.joinPaths(project.sourceDirectory, "src")) + FileInfo.pathSeparator()

    property string libsDir: FileInfo.cleanPath(FileInfo.joinPaths(srcDir, "libs")) + FileInfo.pathSeparator()

    property bool useCombinedLibs: true

    

    // Add dependency on all Qt components that we need

    OctoMYQtDepends {}

    // Add dependency on cpp

    Depends{

        name: "cpp"

    }

    // Enumerate OctoMY lib folders

    OctoMYLibProbe {

        id: octomyLibs

        searchPath: libsDir

    }

    //"QT_DISABLE_DEPRECATED_BEFORE=0x060000" // disables all the APIs deprecated before Qt 6.0.0

    // Tell cpp to look for header files in all the lib folders

    cpp.includePaths: base.concat(octomyLibs.libFolders)

    // Tell cpp all the auto-generated defines for OctoMY libraries

    cpp.defines: base.concat(octomyLibs.libDefines)

    // Tell cpp what version and stdlib we want

    cpp.cxxLanguageVersion: "c++20"

    cpp.cxxStandardLibrary: "libc++"

    install: true

    installDir: qbs.targetOS.contains("qnx") ? FileInfo.joinPaths("/tmp", name, "bin") : base

    OctoMYFiles{

        name: "app_sources"

        prefix: appDir

    }

    // We DON'T use combined libs, include all lib sources directly here

    OctoMYFiles{

        condition: !useCombinedLibs

        name: "lib_sources"

        prefix: libsDir

    }

    // We DO use combined libs, depend on combined lib here

    Depends { 

        condition: useCombinedLibs

        name: "combined"

    }

}

This time we use a bunch of helpers, some of which you already know:

• OctoMYQtDepends: Our helper to include dependency on all the Qt modules that OctoMY™ needs
• OctoMYLibProbe: Our helper to enumeratelibrary folders
• OctoMYFiles: Our helper to list source files in a project that we care about (this is equivalent to tile fil Group in our StaticLibrary above).

Please note the user defined property we made called useCombinedLibs. It will include two different blocks depending on it's value. If it is true, then we have a Depends{ name: "combined"} and if it is not true we include a file group OctoMYFiles that basically lists all the source files of all our libraries in one big list.

This allows us to choose wether we want to build libraries separately and depnd on them or build the sources of the libraries directly into the app.

This concludes the fifth and final part in a series on using Qbs to our benefit  and joy in a non-trivial project, namely OctoMY™

I hope this series was useful, and that it helped you see the many benefits and few shortcommings of Qbs so that you may implement it in your own projects.

Good luck!

Illustrations borrowed from the amazing collection at https://ericjoyner.com/

Qbs tutorial part 4/5: File Groups

 

Selecting files with Groups

In the last part we went into the sub-project file src/libs.qbs in detail, looking at how libs were built. But we left out one important part, namely the Group type in Qbs. This will be the focus of this part! But first our file tree as a reference:

.

├── OctoMY.qbs

├── src

│   ├── agent

│   │   ├── AgentMain.cpp

│   │   ├── AgentMain.hpp

│   │   ├── app.qbs

│   │   └── README.md

│   ├── apps.qbs

│   ├── combined

│   │   └── lib.qbs

│   ├── libs

│   │   ├── libagent

│   │   │   ├── agent

│   │   │   │   ├── Agent.cpp

│   │   │   │   ├── Agent.hpp

│   │   │   │   └── AgentWindow.ui

│   │   │   ├── lib.qbs

│   │   │   └── README.md

│   ├── libs.qbs

├── test

│   ├── common_test

│   │   ├── Common_test.hpp

│   │   ├── CommsTester.cpp

│   │   ├── CommsTester.hpp

│   │   ├── mock

│   │   │   ├── MockCourier.cpp

│   │   │   └── MockCourier.hpp

│   │   ├── resources

│   │   │   ├── icons

│   │   │   │   ├── profile.svg

│   │   │   │   ├── stress.svg

│   │   │   │   └── test.svg

│   │   │   └── test_resources.qrc

│   │   ├── Utility_test.cpp

│   │   └── Utility_test.hpp

│   ├── testLogHandler

│   │   ├── TestLogHandler.cpp

│   │   ├── TestLogHandler.hpp

│   │   └── test.qbs

│   ├── testTryToggle

│   │   ├── TestTryToggle.cpp

│   │   ├── TestTryToggle.hpp

│   │   └── test.qbs

│   └── tests.qbs

└── integration

   └── qbs

     └── imports

            ├── OctoMYApp.qbs

            ├── OctoMYLibProbe.qbs

            ├── OctoMYAutoLib.qbs

            ├── OctoMYTestProbe.qbs

            ├── OctoMYAutoTest.qbs

            ├── OctoMYFiles.qbs

            ├── OctoMYQtDepends.qbs

            └── utils.js

Groups are maybe the most important of all the types in Qbs. This is Qbs' very convenient way of enumerating a named set of files used for input to a build. If we look at the StaticLibrary in the last part, we found this:

// Enumerate source files for this library

    Group{

        name: FileInfo.fileName(path2)+"_sources"

        prefix: fulldir

        files: [

            "**/*.cpp",

            "**/*.hpp",

            "**/*.c",

            "**/*.h",

            "**/*.ui",

            "**/*.qrc"

        ]

    }

Groups are named using the name property which comes in very handy as you will see the names inside QtCreator.

The files property is where you specify the files. In a simple project you can just list files by fulll filename, but Groups also support an intuitive set of glob style wildcards. From the documentation:

When specifying files, you can use the wildcards "*", "?" and "[]", which have their usual meaning. By default, matching files are only picked up directly from the parent directory, but you can tell Qbs to consider the whole directory tree. It is also possible to exclude certain files from the list. The pattern ** used in a pathname expansion context will match all files and zero or more directories and subdirectories.

The prefix property allows you to avoid repeating a long pathname by specifying it only once.

⚠️DANGER⚠️ Please note this very common and dangerous pitfall: the prefix parameter is string based and NOT file based! This is by design. This means that if you omit the directory separator at the end of your prefix then the result will be completely differnt. For example:

Group{

   name: "example1"

   prefix: "mydir/mysubdir"

  files:[ "a.cpp", "b.cpp", "c.cpp"

}

// Results in mydir/mysubdira.cpp, mydir/mysubdirb.cpp, mydir/mysubdirc.cpp which could be what you wanted, but maybe not

Group{

   name: "example2"

   prefix: "mydir/mysubdir/"

  files:[ "a.cpp", "b.cpp", "c.cpp"]

} 

// Results in mydir/mysubdir/a.cpp, mydir/mysubdir/b.cpp, mydir/mysubdir/c.cpp which could be what you wanted, but maybe not

In our StaticLibrary, you will see two strange things in the Group. One strange thing is that we somehow just grab ALL the files of certain types:

files: [

    "**/*.cpp",

    "**/*.hpp",

    "**/*.c",

    "**/*.h",

    "**/*.ui",

    "**/*.qrc"

]

How is this possible?

This is another very powerful feature: Qbs will determine how to process a file from that file's type through the use of FileTaggers and Rules. You no longer have to manually segregate files by types like you had to in qmake through the SOURCES and HEADERS variables. Instead Qbs will simply identify what is a header and what is a source, a resource, a designer ui file, a qml file and so on. In fact, Qbs supports a quite large and growing set of languages, platforms and toolchains. At first this might not seem like a big deal, but it has many benefits.

For one, projects which mix languages and platforms now suddenly will have "nirvana" in the form of one build tool to build it all.

Furthermore, managing projects becomes more fluid. Simply list the filetypes you care about and let Qbs figure out the rest.

Another benefit is that all the rules for building to the different platforms and toolchians is defined in  Qbs syntax, so you can very well extend it to suit your own needs, for example if you create your own domain spesific languages or encouter archaic or exotic toolchains that you depend on in your build, you can create the necessary Rules, FileTaggers and so on to handle themin your Qbs build.

Final note on file Groups is that we use the globstar (**) wildcard. This means "zero or more path elements". We use this because each of the libraries in OctoMY™ will have an unknown number of possibly nested subfolders, and we want to grab sources from all of them. Very convenient!

Now we know how files are selected in Qbs🎉!

This concludes the fourth part in a series on using Qbs to our benefit  and joy in a non-trivial project, namely OctoMY™

In the next part we will look at app.qbs and how it pulls in the necesary dependencies to build our apps.

Illustrations borrowed from the amazing collection at https://ericjoyner.com/

Qbs tutorial part 3/5: Libraries

Building libraries

In the last part we took a look at test/tests.qbs and how it related to the main project file. In this part we will go into the sub-project file src/libs.qbs in detail. But first our file tree as a reference:

.

├── OctoMY.qbs

├── src

│   ├── agent

│   │   ├── AgentMain.cpp

│   │   ├── AgentMain.hpp

│   │   ├── app.qbs

│   │   └── README.md

│   ├── apps.qbs

│   ├── combined

│   │   └── lib.qbs

│   ├── libs

│   │   ├── libagent

│   │   │   ├── agent

│   │   │   │   ├── Agent.cpp

│   │   │   │   ├── Agent.hpp

│   │   │   │   └── AgentWindow.ui

│   │   │   ├── lib.qbs

│   │   │   └── README.md

│   ├── libs.qbs

├── test

│   ├── common_test

│   │   ├── Common_test.hpp

│   │   ├── CommsTester.cpp

│   │   ├── CommsTester.hpp

│   │   ├── mock

│   │   │   ├── MockCourier.cpp

│   │   │   └── MockCourier.hpp

│   │   ├── resources

│   │   │   ├── icons

│   │   │   │   ├── profile.svg

│   │   │   │   ├── stress.svg

│   │   │   │   └── test.svg

│   │   │   └── test_resources.qrc

│   │   ├── Utility_test.cpp

│   │   └── Utility_test.hpp

│   ├── testLogHandler

│   │   ├── TestLogHandler.cpp

│   │   ├── TestLogHandler.hpp

│   │   └── test.qbs

│   ├── testTryToggle

│   │   ├── TestTryToggle.cpp

│   │   ├── TestTryToggle.hpp

│   │   └── test.qbs

│   └── tests.qbs

└── integration

   └── qbs

     └── imports

            ├── OctoMYApp.qbs

            ├── OctoMYLibProbe.qbs

            ├── OctoMYAutoLib.qbs

            ├── OctoMYTestProbe.qbs

            ├── OctoMYAutoTest.qbs

            ├── OctoMYFiles.qbs

            ├── OctoMYQtDepends.qbs

            └── utils.js

Libraries work much the same way as tests, so if you look inside src/libs.qbs you will find a similar reference to OctoMyLibsProbe as you did inside libs/libs.qbs. This probe will expectedly enumerate all folders that start with "lib" and that contain a file called lib.qbs under libs/

So now that all our libs and tests have been enumerated, we can look at the anatomy of a library. Let's use libs/libagent/lib.qbs as an example:

OctoMYAutoLib {

    property string path2:path

}

Again, you might have put two together and realized that OctoMYAutoLib refers to integration/qbs/imports/OctoMYAutoLib.qbs which again contains some sort of magic. This time it is not a Probe, however. It looks like this:

import qbs.FileInfo

StaticLibrary {

    Depends { 

        name: "cpp"

    }

    OctoMYQtDepends {}

    property string libdir: FileInfo.relativePath(project.sourceDirectory, path2)+FileInfo.pathSeparator()

    property string fulldir: FileInfo.cleanPath(path2)+FileInfo.pathSeparator()

    

    name:{

        var n=FileInfo.fileName(path2);

        console.info("Autolib    libdir=" + libdir+", n="+n+", path2="+path2+", fulldir="+fulldir);

        return n;

    }

    

    Export {

        Depends {

            name: "cpp"

        }

        OctoMYQtDepends {}

        property string e:{

            console.info("Auto Lib '"+exportingProduct.name+"' exportingProduct.sourceDirectory="+exportingProduct.sourceDirectory)

            return exportingProduct.sourceDirectory + FileInfo.pathSeparator();

        }

        cpp.includePaths: [ e ]

        cpp.defines: [ "USE_LIB_" + exportingProduct.name.toUpperCase() ]

    }

    

    cpp.includePaths: [ fulldir ]

    cpp.cxxLanguageVersion: "c++20"

    cpp.cxxStandardLibrary: "libc++"

    

    // Enumerate source files for this library

    Group{

        name: FileInfo.fileName(path2)+"_sources"

        prefix: fulldir

        files: [

            "**/*.cpp",

            "**/*.hpp",

            "**/*.c",

            "**/*.h",

            "**/*.ui",

            "**/*.qrc"

        ]

    }

}

This time you can see that we are defining an actual artifact called StaticLibrary. And this introduces a whole slew of new concepts. Let's go thorugh them one at the time from the top.

First we see a definition Depends{ name: "cpp"}

This is powerful feature in Qbs where you can depend on certain features by name to bring them into your project like magic. For example the cpp module contains all the properties and rules for building C++ applications. It is quite extensive. Qbs has a bunch of these modules that you can depen on for all sorts of languages and platforms and toolchains.

Just with that simple line we now have C++ toolcahin at our disposal.

Next comes a friend of ours from the ./integrations/qbs/ folder called OctoMYQtDepends. This time it is a reusable depend statement to specify what Qt modules we want to include in every build of OctoMY. It looks like this:

Depends {

    name: "Qt"

    submodules: [

          "bluetooth"

        , "concurrent"

        , "core"

        , "gui"

        , "multimedia"

        , "multimediawidgets"

        , "openglwidgets"

        , "positioning"

        , "printsupport"

        , "sensors"

        , "serialport"

        , "svgwidgets"

        , "widgets"

        , "xml"

    ]

}

As you can see, it uses the optional submodules syntax of Qbs Depends to specify a list of sub-modules. OctoMY™ consumes pretty much all of Qt so the list of modules is long. Here is the list of Qt modules available.

Next we will look at the Export entry. This is how we tell anyone wishing to link against our StaticLibrary how to do that. We export our dependency on C++ though the Depends {name: "cpp"}, our dependence on Qt through OctoMYQtDepends {}. We also specify where consumers of our library can find the include files through cpp.includePaths and we can specify which settings to use for the C++ compiler and linker with cpp.*.

Ideally these should match the ones used when building the library, and in this case they do, as you can clearly see it is duplicated.

The Group defines the collection of files from which this StaticLibrary will be built, and it deserves a whole part for itself, so we will go through this concept in the next part of this series.

So to summarize our StaticLibrary definition, what does the full statement mean?

In short we put the declaration for each library from one template that will recursively build all source files into a static library. This will ensure that maintaining our 40+ librarie's build instructions which should remain identical at all times is easily done in one place. We don't have to scurry around maintaining 40+ project files which would be a hazzle.

We could also just make one big library that found all the source files in each library's folder. So why did we not go this route?

There are some reasons. For one, we might want to have special commands for some of the libraries while keeping the rest identical. This is now easily carried out by reokacing or extending the project file for that single project.

Another reason is that we might gain some build speed by keeping libraries instead of re-building from source every time.

Now our libraries are built, what comes next?

This concludes the third part in a series on using Qbs to our benefit and joy in a non-trivial project, namely OctoMY™

In the next part we will look at the Group type in Qbs and how we can use it to enumerate the source fiels of our builds.

Illustrations borrowed from the amazing collection at https://ericjoyner.com/

Qbs tutorial part 2/5: Tests

Tests

In the last part we looked at the overal structure of the project as well as the main project file OctoMY.qbs and how it referred to sub-projects. In this part we will go into the sub-project file test/tests.qbs in detail. But first our file tree as a reference:

.

├── OctoMY.qbs

├── src

│   ├── agent

│   │   ├── AgentMain.cpp

│   │   ├── AgentMain.hpp

│   │   ├── app.qbs

│   │   └── README.md

│   ├── apps.qbs

│   ├── combined

│   │   └── lib.qbs

│   ├── libs

│   │   ├── libagent

│   │   │   ├── agent

│   │   │   │   ├── Agent.cpp

│   │   │   │   ├── Agent.hpp

│   │   │   │   └── AgentWindow.ui

│   │   │   ├── lib.qbs

│   │   │   └── README.md

│   ├── libs.qbs

├── test

│   ├── common_test

│   │   ├── Common_test.hpp

│   │   ├── CommsTester.cpp

│   │   ├── CommsTester.hpp

│   │   ├── mock

│   │   │   ├── MockCourier.cpp

│   │   │   └── MockCourier.hpp

│   │   ├── resources

│   │   │   ├── icons

│   │   │   │   ├── profile.svg

│   │   │   │   ├── stress.svg

│   │   │   │   └── test.svg

│   │   │   └── test_resources.qrc

│   │   ├── Utility_test.cpp

│   │   └── Utility_test.hpp

│   ├── testLogHandler

│   │   ├── TestLogHandler.cpp

│   │   ├── TestLogHandler.hpp

│   │   └── test.qbs

│   ├── testTryToggle

│   │   ├── TestTryToggle.cpp

│   │   ├── TestTryToggle.hpp

│   │   └── test.qbs

│   └── tests.qbs

└── integration

   └── qbs

     └── imports

            ├── OctoMYApp.qbs

            ├── OctoMYLibProbe.qbs

            ├── OctoMYAutoLib.qbs

            ├── OctoMYTestProbe.qbs

            ├── OctoMYAutoTest.qbs

            ├── OctoMYFiles.qbs

            ├── OctoMYQtDepends.qbs

            └── utils.js

Looking at test/tests.qbs it looks like this:

import qbs.FileInfo

Project{

    name: "Tests"

    property string srcDir: FileInfo.cleanPath(FileInfo.joinPaths(project.sourceDirectory, "src")) + FileInfo.pathSeparator()

    property string projectDir: FileInfo.cleanPath(project.sourceDirectory) + FileInfo.pathSeparator()

    property string testDir: FileInfo.cleanPath(FileInfo.joinPaths(projectDir, "test")) + FileInfo.pathSeparator()

    property string commonTestDir: testDir + "common_test" + FileInfo.pathSeparator()

    property string commonTestLib: commonTestDir + "lib.qbs"

    

    // Enumerate OctoMY test projects

    OctoMYTestProbe {

        id: octomyTests

        searchPath: testDir

    }

    references: octomyTests.testFiles.concat([commonTestDir])

}

As you can clearly see, this is also a project. Since it is referred to by the top-level project it is in fact a sub-project, and you can see that the name it will display in QtCreator is "Tests".

Further you can see that it has some notable properties:

• srcDir
• projectDir
• testDir
• commonTestDir
• commonTestLib

These are set using JavaScript expressions that use the Qbs FileInfo service. Qbs has many services or libraries with functions that help us with all kinds of things ranging from file and string manipulation to getting information about the platform.

Next we see a new item called OctoMYTestProbe. You might have put two together already and realized where this was defined. In our main project file we used a property called qbsSearchPaths to ask Qbs to look for our user defined re-usable components. In that folder there was an item called OctoMYTestProbe.qbs that Qbs now conveniently has loaded and made available to us.

NOTE: components are only made available in files referred to by the main project for technical reasons. This is one of many reasons why it is a good idea to separate your Qbs project into multiple files, for all but the smalest of projects.

Qbs has a concept of Probes. The job of a probe is to look for things or perform expensive calculations. Probes are executed before the build starts and Qbs has some clever caching mechanisms that ensure they are only executed once. If you are doing anything intense, be it search through folders, calculate hashes or whatever else, Probes are your best friend. Probes also promote code re-use.

Our OctoMYTestProbe.qbs probe looks like this:

import qbs.File

import qbs.FileInfo

Probe{

    // Parameters

    property string name: "OctoMYTestProbe"

    property string searchPath: FileInfo.cleanPath(FileInfo.joinPaths(project.sourceDirectory, "test")) + FileInfo.pathSeparator()

    property string testFileName: "test.qbs"

    property string testDefinePrefix: "OC_USE_TEST_"

    property string commonTestDir:  FileInfo.cleanPath(FileInfo.joinPaths(searchPath, "common_test")) + FileInfo.pathSeparator()

    // Outputs

    property stringList testNames: []

    property stringList testFolders: []

    property stringList testFiles: []

    property stringList testDefines: []

    configure: {

        found=false;

        var raw = File.directoryEntries(searchPath, File.Dirs | File.NoDot | File.NoDotDot);

        testNames = (raw || []).filter(function(dir){

            if(testFileName){

                return dir.startsWith("test") && File.exists(FileInfo.joinPaths(searchPath, dir, testFileName));

            }

            else{

                return dir.startsWith("test");

            }

        });

        testFolders = testNames.map(function(testName){

            return FileInfo.joinPaths(searchPath, testName);

        })

        testFiles = testFolders.map(function(testFolder){

            return FileInfo.joinPaths(testFolder, testFileName);

        })

        testDefines = testNames.map(function(testName){

            return testDefinePrefix + testName.toUpperCase();

        })

        found = testNames.length > 0;

        console.info("Probing returned for '" + name+"':");

        console.info(" + found="+found);

        console.info(" + searchPath="+JSON.stringify(searchPath, null, "\t"));

        console.info(" + testNames="+JSON.stringify(testNames, null, "\t"));

        console.info(" + testFolders="+JSON.stringify(testFolders, null, "\t"));

        console.info(" + testFiles="+JSON.stringify(testFiles, null, "\t"));

    }

}

As you can see, the probe uses the File service to look for directories beginning with "test" that contains a file called "test.qbs".

It sets the special property found to true if the number of folders found is more than zero.

It also logs a bunch of stuff to the console.

Qbs Supports printing of debug strings to the console using console.info() which can be very useful while debugging.

The probe will be ran and produce some useful properties for us:

• testNames - a list of the names of tests found in our project
• testFolders - the folders for each of our tests
• testFiles - the test.qbs file for each test
• testDefines - some defines that refer to our test names

Now when we go back to test/tests.qbs and have a closer look, we will see this:

...

    OctoMYTestProbe {

        id: octomyTests

        searchPath: testDir

    }

    references: octomyTests.testFiles.concat([commonTestDir])

...

As you can tell, we are making an instance of the OctoMYTestProbe called octomyTests, and we pass the calcualted property testFiles, which is a list of qbs files, one for each test, to the references. In other words, we are telling Qbs to read in all these test project qbs files as part of the Test project. In QtCreator you will see that it genereates a full list of tests in the project tree.

So why did we go to all this trouble instead of just naming the tests manually in a list?

Well, now we never have to change this project file again. Whenever we create a new test, it will magically appear thanks to our clever Probe🎉.

This concludes the second part in a series on using Qbs to our benefit and joy in a non-trivial project, namely OctoMY™

In the next part we will look at src/libs.qbs and how it relates to the main project file.

Illustrations borrowed from the amazing collection at https://ericjoyner.com/

Qbs tutorial part 1/5: Main project file

After spending a few gruelling weeks porting my brain to "think in Qbs", I felt ready to take on the non-trivial task of comitting 100% to porting the build system of OctoMY™ from qmake to Qbs. This was in large part possible thanks to the super-human patience and wisdom demonstrated by the super awesome Qbs community, which lives on Discord. Shoutout to ABBAPOH, Psy-Kai and Janet Blackquill, your help was indispensible!

I thought I would document my decisions here for future reference and maybe to serve as a template for others trying to get into Qbs with their non-trivial projects. I will also introduce some concepts and tips & tricks that I picked up along the way.

So first up: top level project structure. OctoMY™ is divided coarsely into 3 parts:

• Apps - The actual programs that we run when we want to use OctoMY™
• Libs - The software components which contains the code of OctoMY™, liked into the apps
• Tests - A bunch of programs, each testing one aspect of the codebase

The file structure of the project looks like this:

.

├── OctoMY.qbs

├── src

│   ├── agent

│   │   ├── AgentMain.cpp

│   │   ├── AgentMain.hpp

│   │   ├── app.qbs

│   │   └── README.md

│   ├── apps.qbs

│   ├── combined

│   │   └── lib.qbs

│   ├── libs

│   │   ├── libagent

│   │   │   ├── agent

│   │   │   │   ├── Agent.cpp

│   │   │   │   ├── Agent.hpp

│   │   │   │   └── AgentWindow.ui

│   │   │   ├── lib.qbs

│   │   │   └── README.md

│   ├── libs.qbs

├── test

│   ├── common_test

│   │   ├── Common_test.hpp

│   │   ├── CommsTester.cpp

│   │   ├── CommsTester.hpp

│   │   ├── mock

│   │   │   ├── MockCourier.cpp

│   │   │   └── MockCourier.hpp

│   │   ├── resources

│   │   │   ├── icons

│   │   │   │   ├── profile.svg

│   │   │   │   ├── stress.svg

│   │   │   │   └── test.svg

│   │   │   └── test_resources.qrc

│   │   ├── Utility_test.cpp

│   │   └── Utility_test.hpp

│   ├── testLogHandler

│   │   ├── TestLogHandler.cpp

│   │   ├── TestLogHandler.hpp

│   │   └── test.qbs

│   ├── testTryToggle

│   │   ├── TestTryToggle.cpp

│   │   ├── TestTryToggle.hpp

│   │   └── test.qbs

│   └── tests.qbs

└── integration

   └── qbs

     └── imports

            ├── OctoMYApp.qbs

            ├── OctoMYLibProbe.qbs

            ├── OctoMYAutoLib.qbs

            ├── OctoMYTestProbe.qbs

            ├── OctoMYAutoTest.qbs

            ├── OctoMYFiles.qbs

            ├── OctoMYQtDepends.qbs

            └── utils.js

So there is a lot to cover here, and I promise that we will go over one part at the time so that it will all make sense in the end!

First, qbs consist of strategically placed text files with the .qbs file extension. Inside these qbs files is a declarative syntax borrowed from QML. Expect to see a bunch of json-like blocks of data with some javascript sprinkled on top.

The top-level file of the project is OctoMY.qbs This marks the entrypoint for qbs, and it is this file which qbs will read first, and this is the file you open in QtCreator to load the project.

Qbs project in QtCreator

As you can see, I have used color coding thoruhgt this article so that you may easily see the link between views. For example, the main project file has been marked red, and the sub-project files that it references yellow in this entire article, so you can readily find them in the file structure above.

OctoMY.qbs looks like this:

import qbs.FileInfo

Project {

    name: "OctoMY™"

    qbsSearchPaths: [ FileInfo.joinPaths(path, "integration", "qbs") + FileInfo.pathSeparator()]

    references: [

           "src/libs.qbs"

          , "src/apps.qbs"

          , "test/tests.qbs"

    ]

}

As you can see, it has some important lines:

• import qbs.FileInfo: This is how we get access to other types and script libraries in qbs. In this case, we need the FileInfo service provided with qbs that allows us to do file operations.
• Project: This indicates that we are defining a new qbs project. "Project" is a qbs type that represents a project. It is used to collect other items inside of it similar to a folder in a filesystem. It can contain other items directly inside of it, or it can refer to files which in turn will contain such items. In our case we only refer to other files through the references property (see below).
• name: This is what shows up inside QtCreator as the name of your project. If you leave it out, Qbs will use the file as a fallback. In other words, this property is optional.
• qbsSearchPaths: This points to where qbs will look for our user defined reusable components, of which there are several in the OctoMY™ project. You don't have to use this feature, but it will serve you well to use it once your Qbs project grows beyond the trivial "Hello World" examples. In this case we tell qbs that this project will look for our components in ./integrations/qbs folder, and you can see (in theproject tree at the top of this article) that it contains some components that we will use from sub projects, such as OctoMYTestProbe.qbs.
• references: References is a list of files that Qbs should read and include in the project. Since we are currently defining a project, we want to include the actual sources and libraries and tests of the project, and that is done by referring to the qbs files which we use to find them. In this case we include 3 sub-projects via the libs.qbs, apps.qbs and test.qbs files.
  

As you can see, I have color coded some files such as the main project file in red, and the sub-project files that it references in yellow in this entire article series, and so you can readily find them in the file structure.

This concludes the first part in a series on using Qbs to our benefit and joy in a non-trivial project, namely OctoMY™

In the next part we will look at test/tests.qbs and how it relates to the main project file.

Illustrations borrowed from the amazing collection at https://ericjoyner.com/