Getting Started

This guide walks through a first analysis with libasp — from connecting to a server to reading back the reports. It assumes an analysis server is listening on tcp://127.0.0.1:5500 (the default; the port is not enforced).

The analysis workflow

Every analysis follows the same five steps. The C API mirrors them directly:

1. Initialize the library once with asp_initialize().

2. Connect to the server with asp_connection_create() / asp_connection_connect().

3. Describe the work: create an asp_workspace_create(), register it with asp_connection_add_workspace(), and add files with asp_connection_add_workspace_file().

4. Run one or more jobs: build an asp_analysis_create() with typed asp_analysis_job_create() entries, then asp_connection_start_analysis().

5. Collect results: wait with asp_connection_wait_analysis() and read them via asp_connection_get_analysis_result().

A minimal client

#include <asp/asp.h>

asp_initialize();

asp_connection *conn = asp_connection_create();
asp_connection_connect(conn, asp_address_nng("tcp://127.0.0.1:5500"), true);

asp_workspace *ws = asp_workspace_create();
asp_connection_add_workspace(conn, ws);
asp_connection_add_workspace_file(conn, ws,
    asp_file_create(asp_address_local_file("analyzed.c"), true));

asp_analysis     *aa  = asp_analysis_create();
asp_analysis_job *job = asp_analysis_job_create();
asp_analysis_job_set_kind(job, ASP_ANALYSIS_JOB_KIND_DEFECTS);
asp_analysis_add_job(aa, job, true);
asp_connection_start_analysis(conn, ws, aa);

asp_analysis_result *aar = asp_analysis_result_create();
asp_connection_wait_analysis(conn, aa);
asp_connection_get_analysis_result(conn, ws, aa, aar);

for (asp_report *r = asp_analysis_result_get_report(aar); r != NULL; )
{
    printf("%s:%u:%u: %s: %s\n",
           asp_report_get_file(r), asp_report_get_line(r),
           asp_report_get_column(r), asp_report_get_rule_id(r),
           asp_report_get_explanation(r));

    asp_report *next = asp_report_next(r);
    asp_report_free(r);
    r = next;
}

asp_analysis_result_free(aar);
asp_analysis_free(aa);
asp_connection_close(conn);
asp_connection_free(conn);
asp_deinitialize();

Beyond defect reports, a result also carries symbol locations (asp_analysis_result_get_symloc()), a call map (asp_analysis_result_get_symcall()) and file-identification data (asp_analysis_result_get_identification_file()). The full demo in demo/main.c exercises all of these.

Memory ownership

Objects are reference-counted and created/destroyed in pairs (*_create / *_free). When a “take ownership” flag is passed as true (for example to asp_connection_connect() or asp_file_create()), the owning object frees the argument for you. Linked-list results (reports, symbols, identification files) are walked with *_next and each node is freed by the caller, as shown above.

Trying the command-line client

The same workflow is available from the shell through asp-cli — see Command-line Client (asp-cli).