= Application debugging =

Some suggestions for debugging applications: 

== Testing without a BOINC client ==

When you have built your application and linked it with the BOINC libraries,
you can run it in 'standalone mode' (without a BOINC core client present).
To do this, put instances of all input files in the same directory (with the proper logical, not physical, names).
The application should run and produce output files (also with their logical names).
You can run the program under a debugger.
When you run an application in standalone mode, the BOINC API will recognize this and take it into account.

Note: {{{boinc_time_to_checkpoint()}}} will always return false, so your application will never checkpoint.

== Testing with a BOINC client but no project ==

Once your application works in standalone mode,
the next step is to run it under the BOINC client.
This will exercise the various forms of interaction with the client.
If you already have a working project, skip to the next section.

You can test an application under the BOINC client,
but without a project server, as shown in the following example.
This example assumes that your executable name is '''test.exe''',
and that it has an input file with logical name '''in''' and physical name '''input.txt''',
and an output file with logical name '''out''' and physical name '''output.txt'''.

 * Make a directory and put the BOINC client there.  Note: you'll need a 6.10.14 or later client.
 * Put the file [http://boinc.berkeley.edu/trac/browser/trunk/boinc/samples/client_state_save.xml samples/client_state_save.xml] in it.
 * Create a file '''account_test.xml''' containing
{{{
<account>
    <master_url>http://test.test</master_url>
    <project_name>test_project</project_name>
</account>
}}}
 * Create a file '''cc_config.xml''' containing
{{{
<cc_config>
    <options>
        <skip_cpu_benchmarks/>
        <unsigned_apps_ok/>
    </options>
</cc_config>
}}}
 * Make a subdirectory '''projects/test.test'''; put '''test.exe''' and '''input.txt''' there.
 * To run the BOINC client (and your app) type
{{{
 cp client_state_save.xml client_state.xml ; boinc
}}}
 (or do the equivalent on Windows).

The client should run your app and then sleep.
Check '''projects/test.test/output.txt''' to verify that it worked.

You can run the BOINC Manager after running the client,
and verify that its various functions
(fraction done reporting, elapsed time reporting, suspend/resume, etc.)
are working.

== Testing with a BOINC client and project ==

If you have a working BOINC project,
you can test applications by repeatedly deploying new app versions in the project.
However, this is tedious if you need to make a lot of fixes.
It's easier to use BOINC's [AnonymousPlatform anonymous platform] mechanism.
To do this:
 * Following the [AnonymousPlatform directions], create a file 'app_info.xml' in the client's project_* directory, with the appropriate name and version number of your application.
 * Each time you build a new version of your application, copy the executable into the project_* directory, making sure it has the appropriate name. Then restart the core client.

On Unix, it's possible to attach a debugger to a running process. Use 'ps' to find the process ID of your application, then something like
{{{
gdb exec_filename PID
}}}
to attach a debugger to it. 

== Checking your workunit and result templates ==

If you haven't set up your workunit and result template files correctly,
or if there's a problem with your application version file setup,
this can be debugged by running the client with the `--exit_before_start`
or `--exit_after_finish` command-line options.

== Getting and deciphering stack traces ==
Once your application is working on your own computers, you're ready to test it with outside computers (alpha testers initially). It may crash on some computers, e.g. because their software or hardware is different from yours. You'll get some information back in the stderr_txt field of the results. If your application called `boinc_init_diagnostics()` with the `BOINC_DIAG_DUMPCALLSTACKENABLED` flag set, and you included symbols, hopefully you'll get symbolic stack traces.

There are separate instructions about [AppDebugWin deciphering a Windows stack trace].

Otherwise, you should at least get numeric (hex) stack traces. There are several techniques for deciphering these. For details see [MacBacktrace Mac Backtrace].  Although that page is written primarily for the Mac, much of it can be used on Linux and UNIX systems as well.