Let's start with a mandatory Hello World example. There is a Hello World example in the overview section, but this time we will create a real-world project.

We will start with a simple Qbs project file:

Project {
   name: "My Project"
   minimumQbsVersion: "2.0"
   references: [
       "app/app.qbs"
   ]
}

Here, we set the name of the project to "My Project" - it is mainly used for IDEs but can also be used to reference a project when setting properties from command-line. We also set the minimumQbsVersion - this property can be useful if the project depends on features that are not present in earlier Qbs versions.

The references property contains the path to a file that describes our application. This file is located in a separate app directory - typically, projects tend to have quite a complicated structure but Qbs does not enforce any specific layout, so we will simply put each product in a separate directory.

The application file sets several properties:

CppApplication {
    name: "My Application"
    targetName: "myapp"
    files: "main.c"
    version: "1.0.0"

    consoleApplication: true
    install: true
    installDebugInformation: true
}

The name property identifies the product. The targetName property sets the name of the resulting binary (without the .exe extension on Windows, which is appended automatically). By default, targetName defaults to name. The files property contains a single main.c file which is a trivial hello world application:

#include <stdio.h>

int main()
{
    printf("Hello, world\n");
    return 0;
}

We set consoleApplication to true to indicate that our application is going to be used from a terminal. For example, on Windows, this will spawn a new console window if you double-click the resulting binary, while on macOS it will create a standalone binary file instead of an application bundle.

By default, the CppApplication.install property is false and thus Qbs does not install the binary. If the install property is true, when building a project, Qbs will also install it into an installation root folder which by default is named install-root and located under the build directory. This folder will contain only resulting artifacts without the build leftovers and files will have the same layout as in the target system. The install property should be set to true for all products that are to be distributed. See the Installing Files section for more details.

We can now build and run our application from the project directory:

chapter-1 $ qbs build
...
Building for configuration default
compiling main.c [My Application]
...
linking myapp [My Application]
...
Build done for configuration default.

chapter-1 $ qbs run
...
Starting target. Full command line: .../default/install-root/usr/local/bin/myapp
Hello, world

The Qbs output to console and default installation location may vary between different platforms.

In most cases, Qbs should be able to find the default compiler (for example, GCC or Clang on Linux, Visual Studio on Windows, or Xcode on macOS), but if that's not the case, see the configuring section.

In the following chapters, we will continue to improve our project: we will add a library and make it configurable.