Arduino Build Events and Hooks

Visual Micro supports all standard Arduino build hooks. Multiple hooks can be specified for each event.

Using Hooks in a Project

To use the hooks simple add a Local Board.txt file to the project (vMicro > Add Code > Local Board.txt) and add the entries as required to the file.

Hook Format

All Hooks are in the format recipe.hooks.____.n.pattern:

Where ____ is the element defined below, and n is the order of the patterns to run...

e.g. This will write a log to a text file in the order 1,2,3 with timestamps

recipe.hooks.prebuild.1.pattern=cmd.exe /c ECHO %DATE% %TIME% Prebuild Hook 1 >> {ProjectDir}BuildTimings.txt
recipe.hooks.prebuild.2.pattern=cmd.exe /c ECHO %DATE% %TIME% Prebuild Hook 2 >> {ProjectDir}BuildTimings.txt
recipe.hooks.prebuild.3.pattern=cmd.exe /c ECHO %DATE% %TIME% Prebuild Hook 3 >> {ProjectDir}BuildTimings.txt

 

Working Directory

The working directory defaults to the {runtime.ide.path}\java\bin folder, and can be overidden per recipe, e.g.

# Set the working directory for prebuild pattern 1 to C:\Users\vMicro\
recipe.hooks.prebuild.1.working_directory=C:\Users\vMicro\

Shell Execute

If set to true then the Operating System shell will be used to start the process

# Specify that the first prebuild pattern uses the Shell to run the command
recipe.hooks.prebuild.1.use_shell_execute=true recipe.hooks.prebuild.1.pattern=ECHO %DATE% %TIME% Prebuild Hook 1 >> {ProjectDir}BuildTimings.txt

Hide New Windows

If set to true no new windows will be created by the hook

recipe.hooks.prebuild.1.create_no_window=false

Error Dialogue

If set to true will show an error dialogue on error

recipe.hooks.prebuild.1.error_dialog=true

Additional vMicro Hooks

Further hooks are available in Visual Micro as described below:

recipe.hooks.core.prebuild_if_changed

Run actions before the core build, if the core needs rebuilding

recipe.hooks.errorbuild

Run actions when there is an error building the project

recipe.hooks.postbuild

Run actions after all build tasks have completed

recipe.hooks.deploy.preupload

Run actions before the Upload action begins

recipe.hooks.deploy.postupload

Run actions after the upload action has completed

Custom Build Hooks

Visual Micro also provides a custombuild event that will override/replace the entire build process. In this case both the standard build and all other build events will be ignored.

All hooks can reference all board/build properties. Licenced Visual Micro users can use a local project board.txt to define project level events. The platform boards.txt or platform.txt or platform.local.txt can also be used to define hooks (see the visual micro explorer for hardware/platform source locations).

Licenced Visual Micro users can also create platform.txt, boards.txt and applications.txt within the "My Visual Micro" folder structure (see docs or ask in forum for more info)

The examples below define 3 hooks that override the entire build process.

The first hook runs a command the way arduino event hooks and compiler commands are normally run. The output is captured and displayed in the visual studio "micro build" output window.

The last two hooks open windows allowing an external or interactive window/process to be displayed to users.

# custom build event property examples
recipe.hooks.custombuild.pattern=somexe.exe "{sketch_path}"
recipe.hooks.custombuild.working_directory={sketch_path}
 
recipe.hooks.custombuild1.pattern=explorer "{sketch_path}"
recipe.hooks.custombuild1.use_shell_execute=true
recipe.hooks.custombuild1.create_no_window=false
 
recipe.hooks.custombuild2.pattern=https://www.google.co.uk?q={sketch_path}
recipe.hooks.custombuild2.use_shell_execute=true
recipe.hooks.custombuild2.create_no_window=false
recipe.hooks.custombuild2.error_dialog=true

 

Debugging Hooks

Some specific hooks are available when debugging, to change the behaivour of the debugger, or to allow for additional controls to be available:

GDB Hooks

# (check Build Output with "vMicro > Compiler > Show Build Properties" Enabled to see which debugging settings are in use in your project)

# Alters the GDB Attach To Process Command for the JLink Debugger
vs-cmd.Debug.AttachtoProcess.tools.jlink.server.initCmd=-c "init"

# Alters the GDB Start Debugging Command for the JLink Debugger
tools.jlink.server.initCmd=-c "init; reset halt"