Using the library to build applications

On UNIX platforms

The DC-API library uses the pkg-config system to help the building of applications. For every backend, two pkg-config modules are available: dcapi-<backend>-client for building client applications and dcapi-<backend>-master for building master applications.

During compilation, the pkg-config --cflags <module> command gives the list of compiler directives (like include file locations) that have to be passed to the compiler whenever one of the DC-API headers is referenced in a source file.

During linking, the pkg-config --libs <module> command will return the list of libraries and linker options required to link the application with DC-API.

If you have built DC-API from source and have installed it at a non-standard location (i.e. not under /usr or /usr/local), you may have to set the PKG_CONFIG_PATH environment variable to point to the directory where the .pc files are located in order to pkg-config to find them.

On Windows

Prerequisites

  • Microsoft Visual Studio 7.1

  • DC-API library and header files

  • Zip file containing the skeleton for an application

Preparing the repository

Unzip the contents of the attached zip file. Copy the following three header files of the DC-API in the include directory: dc_client.h, dc_common.h, dc_win32.h. Copy the following library file of the DC-API in the lib directory: dc_client.lib.

The source code of the application goes into the src directory, which already contains an application skeleton. The Visual Studio Related files are in the win_build directory.

Using Visual Studio to compile the application

Open the application.sln file in Microsoft Visual Studio 7.1 (MVS from now on). Open up the 'Soultion Explorer' window in MVS, if it is not open yet (Ctrl+Alt+L). In the 'Solution Explorer' window you will see the Solution called 'application' to which several subdirectories belong.

Open up the Source Files subdirectory to check that application.c is already added to the solution. Double click on application.c to open it up in MVS. Similarily, the header files are located in the Header Files subdirectory.

Adding more source files to the solution

If you want to add more header or source files, put them in the include or the src directories, respectively. After the files are settled in place right click on the Source Files in the 'Solution Explorer' and choose AddAdd Existing Item from the menu to add the source files. Do the same for the header files to add them to the Header Files directory.

Developing the application

The source file application.c already contains the neccessary include files and some basic functions for an application utilizing the DC-API to compile. The source is structured in an intuitive way. You can use these functions to realize the several functions of a BOINC application (like checkpointing) or you can clear these and develop your own methods.

Compiling the solution

The skeleton 'application' solution is set up to compile with the DC-API. In the middle part on the menu of MVS there is a drop down box showing Debug or Release. With this drop down box, you can select different configurations to compile your application with. Before compiling set this to the appropriate configuration.

If you compile in Debug mode,

  • you'll be able to debug the application by visually stepping through the execution,

  • however, the executable will be bigger and will not be optimalized.

Use this mode for debugging only.

If you compile in Release mode,

  • the executable will be optimalized, resulting in a faster and smaller code,

  • however, you'll not be able to visually debug your applcation.

Use this mode for compiling release versions.

To compile the application select Build solution from the Build menu or press F7. During compilation you will see an output window showing the progress of the compilation.

If compilation fails the last line of the output window will show:

Build: 0 succeeded, 1 failed, 0 skipped

Scroll back in the 'Output Window' to locate the problem and correct it as neccessary.

If compilation is successful the last line of the output window will show:

Build: 1 succeeded, 0 failed, 0 skipped
	

During compilation a subdirectory is created in the win_build directory of the repository having the same name as the current configuration (Debug or Release) You will find the compiled executable in these subdirectories with the name application_1.00_windows_intelx86.exe.

Debugging the application

If the application is successfully compiled in Debug mode, you can debug it visually. During debugging the current directory where the application will look for its input and output files will the win_build directory. Copy the input files of the application in the win_build directory. Select Step Into from the Debug menu to start debugging or press F11. If the application is outdated, MVS will ask to recompile it, select Yes. The applcation will be started and you will see a yellow arrow pointing to the current line of code to be executed. Keep pressing F11 to step through the program lines. If the next call is a function, you can skip the function by pressing F10 (Step Over) and continue debugging on the point where the function returns.

You can set breakpoints in the code by clicking on the grey area next to the program line, where the yellow arrow moves during debugging. A big red dot appears marking a breakpoint.

To clear the breakpoint click on the big red dot or select Clear All Breakpoints (Ctrl+Shift+F9) from the 'Debug' menu. You can start the application in debug mode by selecting Start from the Debug menu, or by pressing F5. Execution will be breaken on the point where you have set breakpoints. To continue execution after a breakpoint press F5.

To stop debugging press Shift+F5 or select the Stop Debugging item in the menu of MVS.

Changing configuration properties

You can change the properties of 'Debug' and 'Release' modes by right clicking on the 'applcation' in the 'Solution Explorer' window and selecting Properties. However, the configuration is already set up to best suit the needs of application development with DC-API so in most cases no configuration option is needed to be changed.