You are viewing an older revision! See the latest version
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.
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.