New website

 Google shut down their classic google sites and the work of migrating to a new home-grown website paid off!

The content is pretty much the same, but the infrastructure is better aligned with our future plans for the project.

OctoMY™ website has been updated!

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/

OctoMY™ will migrate from qmake to Qbs

OctoMY™ has from this date forward decided to standardize on Qbs and migrate from qmake to Qbs. qmake project files will remain for some time until we see that the Qbs project files replace them perfectly before they will be removed. Thanks for all the fish qmake!

This might seem like a strange decision since Qt itself has selected CMake in favor of their own Qbs project, however the benefits Qbs will have to OctoMY™ is substancial compared to what CMake will bring. So here is the list of reasons why OctoMY™ will chose Qbs over CMake:

• CMake is arguably hard to work with, inelegant, cargo-culty, full of legacy, slow, inflexible, archaic and challenging to like
• The main selling point of CMake is that "everyone is using it" and so you will find that a lot of projects support CMake and consuming these projects as dependencies with CMake will be simpler. This is however not relevant for OctoMY™ because we have a strict policy of not depending on any external libraries except Qt framework itself. All the sources are in the tree.
• CMake will allow us to export our project as a dependency to others. Again, this is a mute point as OctoMY™ will not be consumed as a source level dependency.
• Qbs is well supported by Qt (they developed it after all)
• Qbs is well integrated into QtCreator which is very important for OctoMY™ since we depend on that as our main development tool
• Qbs is modern
• Qbs is flexible
• Qbs is fast
• Qbs is multi-platform and has good support for all the platforms that OctoMY™ do and will need support for in the future
• Qbs is open-source
• Qbs is well written (if you peek inside the sources of Qbs, you will probably like what you see)
• Qbs acts as a server that talks to QtCreator over a pipe. This means that QtCreator will better reflect the internal state of Qbs at any given time. For example, it would automatically update the project tree view in QtCreator whenever I saved changes to the project (*.qbs) files, and Qbs would act as expected in many cases where qmake just would not. This gave a surprisingly fluid experience that is addictive.
• Qbs really maxes out your CPU at build time and spends almost zero time on house-keeping. The system is really fast at dependency checking and re-building only the necessary files making your developer experience quite pleasant.
• It has not yet screwed up dependencies even once even in my very demanding project and with me as a demanding user which is quite impressive. qmake would require a full re-build on a regular basis.
• While Qbs works out of the box with Qt, it is not limited to Qt. It has extensions to support a whole load of platforms, languages and frameworks and can integrate with a bunch of developer tools including IDEs, other build tools and more. Especially, Qbs aims to tackle the not-for-the-faint-of-heart builds that target embedded hardware, mobile platforms and other quirky and archaic targets full of demanding requirements such as cross compilation and advanced tool-chain management. Impressive! This means we have some wiggle-room for futer expansion of the OctoMY™ project
• There is a Qbs Discord Server where devs and users of Qbs hang out. This has been one of the best discoveries so far. The amount of patience and wisdom the core team have showed me as a annoying beginner is truely amazing.
• Qbs will hopefully grow and get a much deserved boost in adoption!

Qbs is not perfect, and here are a few of the things that I did NOT like so far:

• The Qbs output is very sparse and debugging Qbs is very difficult for a beginner in the start before you start udnerstanding how it all works under the hood. The log output windows in QtCreator will all just be completely empty even if there definitely are some problems. There are options to add more verbose output, but it is well hidden and off by default. Also the "max verbose" option is not possible to swithc on  at all.
• "printf debugging" is hard since Qbs is declarative. It is definitely possible but very quirky.
• Some of the features in Qbs have severe pitfalls that you are expected to pick up on by yourself. Here are some examples:
• Group prefix is a string, and NOT a file entity. In other words, "someFolder" and "someFolder/" means different things.
• While the documentation is "complete" it is kind of sparse still, and leaves you wondering about implementation details in many cases. For example, does Group.excludeFiles support wildcards like Group.files or not? (The answer is yes, it does, but the documentation does not mention this).

All these downside however, are easy to fix, while arguably the downsides of CMake are not at all easy to fix.

Old dog learns new tricks: Qbs edition

So I had a go at QML a few years ago and it seems like a cool technology and definitely has a lot of potential for creating good user interfaces.

Getting started with QML is easy enough thanks to the examples directly present in QtCreator. You can get up and running quickly and adapt an example to what you want to achieve.

After a while you will stumble upon a bunch of more or less fundamental questions like:

• How can I interface QML with my existing C++ code?
• How can I get the filename and path of the current module from code?
• What is the meaning of life?

Most of these questions are sort of answered in the examples or in the documentation.

So I thought I had enough QML under my belt to tackle Qbs, the misunderstood, does everything right-yet-nobody-uses-it build system invented by Qt.

Qbs lives on it's own domain, has minimalist examples and documentation and seems to be completely neglected by the whole world. But it is using QML under the hood so that is a start.

Or so I thought.

It could very well be me whom is the problem here. After all I am an old fart that has been too long in the industry. I used to joke that "I learned to program before the internet" which is technically true.

But for some reason getting into Qbs has left me feeling extra old. It feels as if there is a great secret that everyone knows except me. But I won't shy away from a good challenge and so I have decided to conquer Qbs before I make my judgement. My hope is that all the promise it holds will be unleashed upon my projects once I unlock it's secrets.

The journey begins!

Brief OctoMY™ update 2023

These are the changes scheduled for early to mid 2023 in the OctoMY™ project:

• Good bye Qt5 hello Qt6
• Refactoring of subsystems relating to media such as speech, video streaming etc
• Once-over of whole project
• New build system

Good bye Qt5 hello Qt6

Perhaps a little overdue, we finally support Qt6. Since we didn't really have a usable build in Qt5, we have just put that behind us and we are going all inn on Q6.

Media subsystem

This derives partly from the Qt6 transition as Qt6 introduced many changes in the underlying media related APIs and partly from the initial implementations in OctoMY™ showing it's age as many were the first parts of the codebase to be implemented and they have suffered from systemic neglect ever since.

Once-over

With a Qt version update and lots of refactoring there is always a risk of introducing lots of healthy little bugs, so this step means simply looking it over and adding tests where they are needed, running all the parts of the oprogram to see if any bugs show up.

New build system

With Qt6 came the astonishingly pragmatic (near-sighted?) decision by Qt project to move Qt away from qmake and on to CMake. The first part I completely understand, while I have learned to love qmake it still is a flawed little program and not really feasible for a large project such as Qt.

The second part of the decision; to transition to CMake feels like substituting pest for cholera. Time will tell if this was a great idea, especialkly since they had an alternative at their hands that shows a lot of rpomise as a proper next generation alternative, namely Qbs.

OctoMY™ project has some build needs that are difficult to express in either build system (being able to not maintain lists of files that are part of the project up front, and being able to dynamically chose wether a library should be linked separately or not) so we will look at adopting Qbs. So far it seems it will suit OctoMY™ quite nicely.

My pet peeves with Qt and QtCreator in 2023

I took a break from C++ and Qt for a few years as I was working on other stuff, and when I came back a unique opportunity presented itself; I could look at Qt from an outsider's perspective not being as biased as before. Well I am biased, Qt is my all time favorite platform so who am I kidding. But I have seen the world beyond and just maybe I can spot some trends where Qt moved while I was gone? This is in essence my mandatory rant on UX in programming tools, with Qt & QtCreator as a backdrop.

NOTE: I am looking at this from a community perspective. I am sure if you pay for Qt your experience will differ in some respects.

Installation

Installing Qt is still terrible, but a little better than it used to be. It still features an install wizard straight from the 1990s era, but at least it has green color to bring it into the future.

Seriously, the wasted potential is staggering. I wish someone would appoint me UX lead on the installer team, I would have a go at setting things straight. Seriously, get in touch! I will let the real-time html layout popping go I promise!

To be fair here are the options:

1. Install ancient mangled version from your favorite Linux distro's repository (not recommended)
2. Build from source.
1. Just rememer to schedule 20 minutes of your time to actually find the download link on the qt.io website. This is what happens when the marketing people takes over. I mean they really tore a page from the the old Microsoft 1990s era FUD tactic playbook here. The only contender is the delete account wizard in the Boo dating app.
2. Once you have the source.... uhm. ok so yes. I will... follow these steps and. Uhm.. It is almost as if someone made it extra hard on purpose.
3. Use some 3rd party Docker image that encapsualtes the build. Because there are no official ones. Seriously, Qt company has no official Docker images to use their shit in 2023.
4. Download online installer:
1. On linux; a payloaded bash script with a windows style install wizard inside.
2. On OSX; an img with a windows style wizard inside.
3. On Windows; a native executable with a windows style wizard inside.
4. The wizard has the worst UX of any installer I have ever used, and I have used alot of installers in my lifetime. It is actually inexcusable.
5. Download offline installer:
1. Nope, can't find it anymore. Is it there? Well you did a good job hiding it. PEBCAK.
6. Download prebuilt binaries in ZIP format.
1. I don't know if they even exist because all the files are so well hidden. If the actually exist then I am sorry for being a retard. PEBCAK.

Migration to Qt6

Migrating from Qt5 to Qt6 in my projects was actually not that bad. It took a day of search/replace/copy/paste for a fairly large codebase. Luckily I had lot's of tests to verify my changes but still the experience was good overal. QRegularExpression and QMedia* were the most hard to adapt.

The documentation spesific to migration was OK, but it could definitely have been much better. I would have loved to see a dropdown at the top of documentation pages where you could select the version you care about instead of fumbling around with google to find the relevant version. Also a collapsed comment on migration next to each deprecated member would be really helpful, instead of having all migration stuff collected on one big page.

Good documentation is one of the best sides of Qt so not complaining too much here!

CMake

CMake? SERIOUSLY?

I know this is a controversial topic. A lot of people like CMake, and a large minority dislike it. And I have a fairly strong opinion myself. Here is my breakdown;

I think that the people that like CMake like it for a completely different reason than why the other people dislike it. The people that like CMake are very pragmatic. They made it work with CMake and then it works and now we can go do something else. Or they were told by their non-technical boss to use CMake beacuse "customer X uses CMake and we must align with them".

The people that don't like CMake are more opportunistic and perfectionistic. I suspect there is a good overlap in this group with those that liked Qbs for this reason. They just can't look at CMake next to Qbs or qmake and think that CMake is the better choice. This group think (and I agree with them) while the rest of industry selected CMake, that alone is not a good enough argument to use it. Instead we should strive to surpass it on every metric beyond "popularity by mediocre middle managers" (to put it on point).

OctoMY™ is currently on a semi-hacked qmake setup that works great, but we are looking at Qbs to see if that could be even better. For OctoMY™ CMake isn't even remotely on the radar.

File types support

I don't know if this is just my memory failing me, but I definitely can't remember that there was this good support for non-Qt related filetypes like Dockerfiles, .dockerignore, *.py, *.js, *.sh, *.md and so on. After a quick highligter update they all seem to highlight beautifullty and support normal indentation. Good job!

File Operations

This peeve goes way back. Unfortunately it has worsened over time. It has several facets. I will start with the most annoying and obvious for me.

QtCreator is an IDE, which stands for Integrated Development Environment. Why is it called that? Because in olden times we used to have a development cycle like this: 

1. Open source in editor, make changes and save
2. Open terminal, invoke build command
3. Open debugger invoke program, debug, find error
4. Go back to editor make changes
5. Repeat

And conversely, the IDE will allow you to do all this from within one program, thus being "integrated".

QtCreator delivers wonderfully on this workflow with only minor annoyances, so well done!

However the IDE also must support other workflows that are very common in software development. Many of them are file related, for example:

-- As a software developer, I want to add an existing file inside my project folder to the project

or 

-- As a software developer, I want to move a file that is in a subfolder of my project into another folder

If you take ANYTHING away from this blog post, please let it be this next sentence: There really are a ton of small usecases in a developer tool that are deceivingly easy to ignore that will make or break the very essence of that tool.

Does it have shiny beautiful icons? Does it load and save projects and files blistering fast? Does it look good on all supported platforms? All good and well. But does it support the bread and butter daily file operations of a seasoned developer?

We don't want another shiny wizard. We want keyboard shortcuts, tricks and tips that work on a low level. Stuff that bear witness that the tool was made by ONE OF US. Example, it used to be that you could just rename a file in the tree view in QtCreator and use relative paths like so:

"../newsubfolder/myfile.cpp" and it would magically understand what you meant; "move myfile.cpp from it's current location  to newsubfolder". No need to bring up a menu, a bloated wizard, an external commandline or file manager.

This disappeared at some point for unknown reason. And of course being able to just move the file with the mouse like normal human being is too much to ask so I won't ask it.

Mandatory rant on UX in programming tools

If you read any good book on UX (like Don't make me think) it will certainly have a bias towards mass market appeal. What do I mean? I mean that it is part of UX syllabus and training that you should follow what the average user thinks and focus on that exclusively, remove everything else (yes actively removing it to avoid detraction of attention which is bad in UX).

If you hire a hard working, well meaning, highly educated UX person straight from school with excellent grades she may very well demolish a good software developer tool because she will in the best case misread or worst case underestimate the users of that tool.

In an IDE like QtCreator this is dangerous because we, the users, are a really smart bunch. The "average" C++ developer is not the one that benefits the company the most, it is the right side of the bell curve that will. Sure developer culture has transitions from being hero base to team based, but we all know a person or two that just are one step above the rest. And the tools should NOT deter those team members!

The sad part is that often it is the littel things, like the neat file-system hacks in the tree editor that nobody knows about. But JP the robot knows..

Media support

In general the refactoring of media support in Qt6 seems level headed. However there is one use case that has not been addressed and it is super annoying:

-- As a software developer, I want to convert a sequence of QImage into a video stream using only Qt (no external dependencies)

It is understood that this will be limited by the media codecs available on the platform, and maybe not be available on all platforms. But it is in my opinion essential for Qt to support this basic usecase.

We are not all Steven Spielberg that crave the best 8k full format presentations. We just want to chuck these QImages into a video file and save it on youtube before calling it a day. It is 2023 after all. I don't want to werstle ffmpeg or libav into my project, that is why I use Qt, so I DON'T have to deal with platform spesific stuff. The annoying part is that Qt is so close! It already integration with the native media frameworks, so why can't they just add that 200 lines to support this out of the box?

I am not alone thinking about this, my question about encoding video from a sequence of QImages from 6 years ago has 63 votes and still no resolution.

Other annoyances

Finally a list of minor anoyances in QtCreator that I felt needed to come of my chest after years of brooding.

1. The refresh action is missing in the file tree so now I find myself closing and reopeng the program every time a file has changed outside QtCreator. Luckily closing and opening QtCreatos is now super fast for some reason. It feels really snappy, so good job on that at least...
2. The swap between source and header key combination is not <ctrl>+<tab> by default. C'mon guys.
3. There is no key combination for switching between design view and editor view, and for some inexplicable reason, I am always moved to look at my design in read-only XML. dafuq?
4. The editor view for design is READ ONLY? I have to open an external text editor to edit the XML for my design? SERIOUSLY? Why don't you just remove editor view entirely, and make it a special operation to edit for those rare cases when that is even remotely relevant? Am I the only one who is annoyed by this?
5. Design view still takes up the whole screen. On modern 4k displays this is a travesty, a UX abomination. The Designer editor should really present inside a normal editor view.
6. There is no "collapse all" and "uncollapse all" buttons in tree view. I have to dig thorugh a submenu. I might as well collaps and uncollaps the tree manually and it will be faster than finding those actions *sigh*.
7. There are still issues with scaling for high DPI screens. The issues view cannot be zoomed like the other views(??) and is sometimes displaying text in way too small font.
8. The "split side by side" is wonderful, however moving the separator is not intuitive. Expected is that "everything stays the same except the size of the two views next to the separator will change in size. Actual is "depending on which separator I move, SOME windows will stretch and other not". It should be super easy to fix, just remove the separator widget in place of a horizontal layout and add widgets to take mouse dragging to change the layout. Why is this not fixed ages ago?
9. It is sometimes desirable to view files that are NOT in your project in the tree view. Yes I know, radical thought. How about adding the option to render all files found in directory with the files that are not part of the project grayed slightly out? You could even add an option to "include in proejct". Radical I know.

This concludes my rant, I hope that despite being harsh at times, it shines through how very much I love Qt. I think there is truth in the Norwegian saying "man tukter den man elsker" literally "You hurt those you love". I  yearn for it to be event better!