Compile API

Mbed OS 2 and Mbed OS 5

This is the handbook for Mbed OS 2. If you’re working with Mbed OS 5, please see the new handbook.

General overview

The mbed compile API allows compilation of either programs in your workspace or repositories published on mbed. This is the same API as is used by our online IDE, so the results will be identical. Requesting a compile returns a unique id, which can be used for checking on the progress of your compilation or downloading the resulting binary.

Helper script

This page describes the raw commands required to start a build. There is a python script and a javascript example which automates this process. The python script currently only supports Repository compilation, but the javascript example support passing in parameters as well.

Authentication

The authentication method currently available is HTTP Basic authentication. Although it is possible to log into os.mbed.com with your email address the Compile API only accepts your username. Using your email address will not work. If you don't know your username you can see it in URLs for pages such as the My Code page.

Starting a compile

POST https://build.mbed.com/api/v2/tasks/compiler/start/

This call requests that compilation is started. The call will return a build ID in response immediately.

Parameters

platform Platform name

Selects the platform to target during compilation.

The value is the unique name of the platform taken from it's platform page. In the case of http://os.mbed.com/platforms/ST-Nucleo-F103RB/ the platform name is ST-Nucleo-F103RB. Note that you must have the platform added to your account.

repo Repository URL

Optional. Supply a URL to a repository on mbed you wish to compile.

program Workspace program name

Optional: Supply the name of a program in your online IDE workspace you wish to compile.

Note

You must supply one of repo or program parameters.

clean True

Optional. Forces clean recompile of all sources. For larger programs setting clean to True is considerably slower. For standard incremental compiles omit this parameter.

Example request using curl

curl  https://build.mbed.com/api/v2/tasks/compiler/start/ -X POST -d "platform=mbed-lpc1768&program=mbed_blinky" --user dan

{
    "code": 200,
    "errors": null,
    "warnings": null,
    "meta": null,
    "result": {
        "display_notices": null,
        "data": {
            "task_id": "4356cb76-7df2-458b-9708-705fb62e8280"
        },
        "display_warnings": null,
        "display_errors": null,
        "result_meta": null
    },
    "notices": null
}

Retrieving build status and output

GET https://build.mbed.com/api/v2/tasks/compiler/output/<task_id>/

The task_id returned when starting your compile is part of the URL above.

Example of in-progress compilation output using curl

curl  https://build.mbed.com/api/v2/tasks/compiler/output/4356cb76-7df2-458b-9708-705fb62e8280 --user dan
{
    "code": 200,
    "errors": null,
    "warnings": null,
    "meta": null,
    "result": {
        "display_notices": null,
        "data": {
            "task_complete": false,
            "task_status": "PENDING",
            "new_messages": [
                {
                    "action": "scan",
                    "type": "progress",
                    "file": "/src"
                },
                {
                    "action": "scan",
                    "type": "progress",
                    "file": "/extras"
                },
                {
                    "action": "compile",
                    "percent": 100.0,
                    "type": "progress",
                    "file": "/src/main.cpp"
                }
            ],
            "task_id": "4356cb76-7df2-458b-9708-705fb62e8280"
        },
        "display_warnings": null,
        "display_errors": null,
        "result_meta": null
    },
    "notices": null
}

Note the new_messages element. This contains an ordered list of messages from the mbed build system.

You may re-request this api call several times to get near realtime updates on your compile, but you will never receive the same message twice as output. Calling this URL consumes those messages.

Example of completed compilation

curl  https://build.mbed.com/api/v2/tasks/compiler/output/4356cb76-7df2-458b-9708-705fb62e8280 --user dan
{                                                                                                                                                                           
    "code": 200,
    "errors": null,
    "warnings": null,
    "meta": null,
    "result": {
        "display_notices": null,
        "data": {
            "binary": "mbed_blinky4df_46027.LPC1768.bin",
            "task_status": "SUCCESS",
            "compilation_success": true,
            "task_id": "4356cb76-7df2-458b-9708-705fb62e8280",
            "finished_at": "2014-04-16 22:41:33.423139",
            "task_complete": true,
            "binary_naming": null,
            "program": "mbed_blinky4df_46027",
            "new_messages": [
                {
                    "action": "link",
                    "type": "progress",
                    "file": "mbed_blinky4df_46027"
                },
                {
                    "action": "elf2bin",
                    "type": "progress",
                    "file": "mbed_blinky4df_46027"
                },
                {
                    "message": "LPC Patch mbed_blinky4df_46027.LPC1768.bin",
                    "type": "debug"
                }
            ],
            "time_taken": 2.746838,
            "started_at": "2014-04-16 22:41:30.676301",
            "link_totals": {
                "zidata": 28,
                "code": 1776,
                "codeincdata": 172,
                "rodata": 232,
                "debug": 1312,
                "rwdata": 16
            },
            "microseconds_taken": 746838,
            "seconds_taken": 2
        },
        "display_warnings": null,
        "display_errors": null,
        "result_meta": null
    },
    "notices": null
}

This output is an example of a completed compilation task. In this case the compilation has succeeded..

The build system will return some information about the task as well as the filename of the binary generated.

Downloading compiled binaries

GET https://build.mbed.com/api/v2/tasks/compiler/bin/

Example:

curl "https://build.mbed.com/api/v2/tasks/compiler/bin/?binary=mbed_blinky.LPC1768.bin&program=mbed_blinky" --user dan -o myprogram.bin

Parameters

binary Name of the binary returned by the output API call.

program Name of the program returned by the output API call

repomode If this was a compile of a repository, this must be set

task_id The task to retrieve the binary of

Cancelling a compile

POST https://build.mbed.com/api/v2/tasks/compiler/cancel/

Parameters

task_id - The task to cancel

You can also cancel a compile by using the Cancel api call. Note that you cannot compile the same program more than once at a time. The program is locked until any compiles against it finish. The cancel call can be used to abort a compilation and release the lock.

Notes

Notice that there is a timeout set between the calls. What that means is that after some time has passed, if not a new call has been made for a ticket, then the ticket is marked as invalid and not further calls for this ticket are accepted.