Cross-platform C SDK logo

Cross-platform C SDK

New project

❮ Back
Next ❯
This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

I see myself as a technical person who chose a great project and a great way of doing that project. Linus Torvalds.


In Quick start we have seen how to get the SDK and compile the sample applications. We have also learned about the basic structure of Hello, World!. The time has come to create our own applications, but first we will delve a little deeper into what we just downloaded.


1. Solutions and projects

In Visual Studio (and Xcode or GNU-Make) there is the concept of a solution which is, in essence, a container for projects that have some kind of relationship. For its part, a project is an executable program or a library. When you cloned the NAppGUI repository in C:\nappgui_sdk you got the template of a cross-platform software solution (Figure 1):

Capture of the directories that make up a multiplatform solution.
Figure 1: Solution ready to start programming, after cloning it from GitHub.
  • inc: SDK header files.
  • lib: Pre-compiled versions of the NAppGUI libraries, for Windows, macOS and Linux systems (x86, x64, arm depending on the case).
  • prj: Files that CMake will use to generate build scripts or solutions.
  • src: Source code of the examples and future location of your own projects.

At the same time, you created a working directory (nappgui_build) which is where the intermediate files, the Makefiles, the executables and everything generated from source code will go. At this point you have to be clear about several things:

  • You are not limited to one solution. You can create as many as necessary. The following is perfectly valid:
  • C:\>
     
    
    git clone https://github.com/frang75/nappgui.git nappgui_sdk
    git clone https://github.com/frang75/nappgui.git my_solution
    git clone https://github.com/frang75/nappgui.git other_solution
    ...
    
  • The build directories are automatically created by CMake and contain the Visual Studo (.sln), Xcode (.xcodeproj) solution or the Makefiles needed to compile and link on Linux. You do not have to configure anything, or edit the Makefiles by hand, or link libraries, or indicate compiler options, or establish dependencies or anything at all. CMake has taken care of everything using the script /src/CMakeLists.txt and the files in the directory /prj.
Contrary to what normally happens, VS projects (.sln/.vcxproj), Xcode (.xcodeproj) or Makefiles are NOT part of the source code. They are created automatically by CMake and included in the build directory. Any manual changes you make to them will be removed when CMake is run again.
  • A build directory can be regenerated at any time, so you can delete them without fear of losing crucial information. You should never include them in the repository or make backup copies. They draw a clear line between the source code and the generated products.
  • Any change you make to the structure of the source code, such as adding or removing files, creating a library or a new executable, will force you to update the build directory, executing cmake again.

2. Command line or IDE

As we saw in Quick start using a couple of commands from the terminal we can (re)generate and (re)compile our solution:

C:\nappgui_build>
 
cmake ../nappgui_sdk/src

// Windows
msbuild NAppGUI.sln

// macOS
xcodebuild

// Linux
make

This will give us the freedom to use any code editor. However, the usual thing will be to work directly with Visual Studio, Xcode or some Linux IDE where you can edit and debug your programs more comfortably. Let's see how to work with the graphical version of CMake and Visual Studio.

In Portability you will have detailed information on how to integrate NAppGUI in Xcode, Eclipse or other versions of Visual Studio.
  • We open CMake.
  • Where is the source code: C:\nappgui_sdk\src.
  • Where to build the binaries: C:\nappgui_build.
  • Press [Configure]. CMake will ask you for the compiler version (the -G option). We use "Visual Studio 16 2019" (Figure 2).
  • Capture of the CMake dialog to set the generator.
    Figure 2: Compiler selection in CMake. This screen will only appear the first time.
  • Press [Generate] (Figure 3). The solution NAppGUI.sln will be created in C:\nappgui_build.
  • Press [Open Project] to open this solution in Visual Studio.
  • Capture of CMake building the solution in Visual Studio.
    Figure 3: Generation of NAppGUI.sln using CMake.
  • Already within Visual Studio, Build->Build Solution.
  • Right click on demo/Products in the Solution Explorer and Set as StartUp Project.
  • Debug->Start Debugging.
  • We can now debug the sample application Products (Figure 4).
  • Capture the Visual Studio debugger running the sample application.
    Figure 4: Debugging samples in Visual Studio.
From here on we will continue to use Visual Studio. You can go back to the command line if you feel more comfortable.

3. Desktop application

We are going to create a new desktop application. To do this, open the file /src/CMakeLists.txt and add the following line at the end (Figure 5):

src/CMakeLists.txt
1
2
# Your projects here!
desktopApp("MyNewApp" "myapp"" "" NRC_EMBEDDED)
Visual Studio editor modifying the CMakeLists.txt.
Figure 5: Adding a new application in our solution.

In CMake, click [Generate] again. This causes /src/CMakeLists.txt to be reprocessed including the new project in the solution. Visual Studio will warn you that something has changed and should reload the solution (Figure 6).

Visual Studio warning after adding a new project.
Figure 6: Visual Studio notice to reload the solution.
  • You will see that CMake has created a new project called MyNewApp within the solution (Figure 7).
  • Visual Studio Solution Explorer screenshot where the new project appears.
    Figure 7: Project MyNewApp just added to the solution.

If you compile and run MyNewApp, you will realize that it is nothing but the Hello, World!, as this is the default template for every new desktop application. An Application icon has also been assigned by default, but we can change it later. If we delve into the syntax of the desktopApp command that we just added to the CMakeLists.txt, we have:

1
2
3
desktopApp("MyNewApp" "myapp" "" NRC_EMBEDDED)

desktopApp(appName path depends nrcMode)
  • appName: The name of the application.
  • path: Relative path to /src where the project will be located (in this case C:\nappgui_sdk\src\myapp). Any path depth is supported. For example, "games/myapp" will create the project in C:\nappgui_sdk\src\games\myapp and "demo/games/myapp" in C:\nappgui_sdk\src\demo\games\myapp.
  • depends: All desktop applications link by default to the NAppGUI SDK libraries. If the application needs additional dependencies, such as libraries created by yourself, we will write them in this field separated by semicolons (eg. "physics;render"). As in this project we don't have any, we pass an empty string (""). In Libraries you have an example of applications with dependencies.
  • nrcMode: How resources will be managed. At the moment, NRC_EMBEDDED. We will delve into them in the chapter Resources.
You can create as many applications within the same solution as you want. You just have to repeat the process, adding new desktopApp() to the script CMakeLists.txt.

4. Add files

Going back to the MyNewApp project, we see that it only has one source code file (mynewapp.c). Create a couple of new files myfunc.c and myfunc.h in C:\nappgui_sdk\src\myapp from Visual Studio or directly from the Windows Explorer. Open them and add these lines:

myfunc.h
1
2
3
4
5
// Example of new header

#include "core.hxx"

real32_t myadd_func(real32_t a, real32_t b);
myfunc.c
1
2
3
4
5
6
7
8
// Example of new c file

#include "myfunc.h"

real32_t myadd_func(real32_t a, real32_t b)
{
    return a + b;
}

Open mynewapp.c and edit the i_OnButton function.

mynewapp.c
1
2
3
4
5
6
7
8
9
...
static void i_OnButton(App *app, Event *e)
{
    real32_t res = myadd_func(56.4f, 23.3f);
    textview_printf(app->text, "Button click (%d-%.2f)\n", app->clicks, res);
    app->clicks += 1;
    unref(e);
}
...

Press [Configure] and [Generate] in CMake to update the solution. Visual Studio reports back to us that there have been changes to the MyNewApp project (Figure 8). Just press [Reload Solution].

Warning displayed by Visual Studio, when detecting that new files have been added.
Figure 8: Visual Studio warns about new files. Press [Reload Solution].

Recompile and run MyNewApp to see the changes you just made.

You can create subfolders within the src/myapp directory to better organize your files. CMake will "clone" this directory structure within the MyNewApp project in Visual Studio.
At this point we recommend that you spend some time researching, compiling and testing the examples in the demo and howto folders.

5. Console application

In addition to desktop applications with graphical environment, you may need to create command line utilities within the same solution. The mechanism is practically the same. Open your /src/CMakeLists.txt and add this line:

src/CMakeLists.txt
1
2
# Your projects here!
commandApp("utils/myutil" "core" NRC_NONE)

When you press [Configure] and [Generate] in CMake, Visual Studio will alert you that you must reload the solution, in the same way that it happened with our previous application. A new project will have been created in C:\nappgui_sdk\src\utils\myutil, but this time if you compile and run it, no window will appear. You will only see a message in the Visual Studio console:

1
Hello world!

If you open myutil.c you will find the code that has generated the previous output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
/* NAppGUI Console Application */
    
#include "coreall.h"

int main(int argc, char *argv[])
{
    unref(argc);
    unref(argv);
    core_start();
    bstd_printf("Hello world!\n");
    core_finish();
    return 0;
}

Which is the typical template for a C program, which has been supported by the core library. From here, we can modify the code and compile. CMake has already configured everything for us. Let's go back to src/CMakeLists.txt to review the previous line:

src/CMakeLists.txt
1
2
3
commandApp("utils/myutil" "core" NRC_NONE)

commandApp(appPath depends nrcMode)
  • appPath: Directory of the application within the solution and name of the executable (myutil).
  • depends: Dependencies. A command line application does not add any dependencies by default, unlike desktop applications. We recommend including, at least, a dependency with Core ("core") since it contains a great variety of functions that can facilitate development. In The Big Picture you have a diagram of the libraries included in the package and their dependencies.
  • nrcMode: NRC_NONE, NRC_EMBEDDED or NRC_PACKED. Resource distribution.

It goes without saying that we can add new files and subfolders to the project in a similar way as we did in desktop applications.

❮ Back
Next ❯