John Whittington 81673d4666 Support for generation of project tags file

Considering the number of project files spread in different locations
when developing an Arduino project, proper use of tags can be difficult;
resolving beyond local functions.

I've added automatic generation of a tags file, which includes:

* Standard ctags source in project dir (.c, .cpp, .h)
* Arduino source in project dir (.ide, .pde)
* Arduino core based on detected project core from Arduino install.
* Included Arduino libraries from user library folder.

As a Vim user I find this hugely useful and think it would be a useful
addtion for others. Target has been added as `make tags`.

2017-06-04 10:47:04 +01:00

21 KiB

Raw Blame History

Documentation of variables

The following are the different variables that can be overwritten in the user makefiles.

Global variables
Installation/Directory variables
Arduino IDE variables
Sketch related variables
ISP programming variables
Compiler/Executable variables
Avrdude setting variables
Bootloader variables
ChipKIT variables
Ctags variables

Global variables

ARDUINO_QUIET

Description:

Suppress printing of Arduino-Makefile configuration.

Defaults to 0 (unset/disabled).

Example:

ARDUINO_QUIET = 1

Requirement: Optional

Installation/Directory variables

ARDMK_DIR

Description:

Directory where the *.mk files are stored.

Usually can be auto-detected as parent of Arduino.mk.

Example:

ARDMK_DIR = /usr/share/arduino

Requirement: Optional

AVR_TOOLS_DIR

Description:

Directory where tools such as avrdude, avr-g++, avr-gcc, etc. are stored in the bin/ subdirectory.

Usually can be auto-detected from $PATH as SYSTEMPATH_AVR_TOOLS_DIR or as BUNDLED_AVR_TOOLS_DIR within the Arduino distribution.

Example:

AVR_TOOLS_DIR = /usr
# or
AVR_TOOLS_DIR = /usr/share/arduino/hardware/tools/avr

Requirement: Optional

RESET_CMD

Description:

Command to reset the MCU.

Defaults to ard-reset-arduino with the extra --caterina flag for atmega32u4 boards.

Example:

RESET_CMD = $(HOME)/gertduino/reset

Requirement: Optional

Arduino IDE variables

ARDUINO_DIR

Description:

Directory where the Arduino IDE and/or core files are stored. Usually can be auto-detected as AUTO_ARDUINO_DIR.

Example:

# Linux
ARDUINO_DIR = /usr/share/arduino
# Mac OS X
ARDUINO_DIR = /Applications/Arduino.app/Contents/Resources/Java
# Mac OSX with IDE 1.5+
ARDUINO_DIR = /Applications/Arduino.app/Contents/Java

Requirement: Optional

ARDUINO_PLATFORM_LIB_PATH

Description:

Directory where the Arduino platform dependent libraries are stored. (Used only for Arduino 1.5+)

Example:

ARDUINO_PLATFORM_LIB_PATH = /usr/share/arduino/hardware/arduino/avr/libraries

Requirement: Optional

ARDUINO_VERSION

Description:

Version string for Arduino IDE and/or core.

Usually can be auto-detected as AUTO_ARDUINO_VERSION from /usr/share/arduino/lib/version.txt

Example:

ARDUINO_VERSION = 105

Requirement: Optional

ARCHITECTURE

Description:

Architecture for Arduino 1.5+

Defaults to unset for 1.0 or avr for 1.5+

Example:

ARCHITECTURE = sam

Requirement: Optional

ARDMK_VENDOR

Description:

Board vendor/maintainer.

Defaults to arduino

Example:

ARDMK_VENDOR = sparkfun

Requirement: Optional

ARDUINO_SKETCHBOOK

Description:

Path to sketchbook directory.

Usually can be auto-detected from the Arduino preferences.txt file or the default $(HOME)/sketchbook

Example:

ARDUINO_SKETCHBOOK = $(HOME)/sketches

Requirement: Optional

ARDUINO_PREFERENCES_PATH

Description:

Path to Arduino preferences.txt file.

Usually can be auto-detected as AUTO_ARDUINO_PREFERENCES from the defaults:

on Linux (1.0): $(HOME)/.arduino/preferences.txt
on Linux (1.5+): $(HOME)/.arduino15/preferences.txt
on Mac OS X (1.0): $(HOME)/Library/Arduino/preferences.txt
on Mac OS X (1.5+): $(HOME)/Library/Arduino15/preferences.txt

Example:

ARDUINO_PREFERENCES_PATH = $(HOME)/sketches/preferences.txt

Requirement: Optional

ARDUINO_CORE_PATH

Description:

Path to standard Arduino core files.

Example:

ARDUINO_CORE_PATH = /usr/share/arduino/hardware/arduino/cores/arduino

Requirement: Optional

ARDUINO_LIBS

Description:

Any libraries you intend to include.

Usually can be auto-detected from the sketch. Separated by spaces. If the library has a /utility folder (like SD or Wire library), then the utility folder should also be specified.

Example:

ARDUINO_LIBS = SD SD/utility Wire Wire/utility

Requirement: Optional

BOARD_TAG

Description:

Device type as listed in boards.txt or make show_boards.

Example:

BOARD_TAG = uno or mega2560

Requirement: Mandatory

BOARD_SUB

Description:

1.5+ submenu as listed in boards.txt or make show_submenu.

Example:

# diecimila.name=Arduino Duemilanove or Diecimila
BOARD_TAG=diecimila

# diecimila.menu.cpu.atmega168=ATmega168
BOARD_SUB=atmega168

Requirement: Mandatory for 1.5+ if using a submenu CPU

MONITOR_PORT

Description:

Path to serial (USB) device used for uploading/serial comms.

Example:

# Linux
MONITOR_PORT = /dev/ttyUSB0
# or
MONITOR_PORT = /dev/ttyACM0
# Mac OS X
MONITOR_PORT = /dev/cu.usb*
# Windows
MONITOR_PORT = com3

Requirement: Mandatory

FORCE_MONITOR_PORT

Description:

Skip the MONITOR_PORT existance check.

Example:

# Enable
FORCE_MONITOR_PORT = true
# Disable (default)
undefine FORCE_MONITOR_PORT

Requirement: Optional

USER_LIB_PATH

Description:

Directory where additional libraries are stored.

Defaults to libraries directory within user's sketchbook.

Example:

# Linux
USER_LIB_PATH = $(HOME)/sketchbook/libraries
# For a random project on *nix
USER_LIB_PATH = /path/to/my/project

Requirement: Optional

OBJDIR

Description:

Directory where binaries and compiled files are put.

Defaults to build-$(BOARD_TAG) in your Makefile directory.

Example:

OBJDIR = /path/to/my/project-directory/bin

Requirement: Optional

TARGET

Description:

What name you would like for generated target files.

Defaults to the name of your current working directory, but with underscores (_) instead of spaces.

Example:

TARGET = my-project

Will generate targets like my-project.hex and my-project.elf.

Requirement: Optional

ALTERNATE_CORE

Description:

Non-standard core for Arduino-unsupported chips like the ATtiny.

Example:

# HLT core
ALTERNATE_CORE = attiny-master
# tiny core
ALTERNATE_CORE = arduino-tiny
# tiny core 2
ALTERNATE_CORE = tiny2

Requirement: Optional

ARDUINO_VAR_PATH

Description:

Path to non-standard core's variant files.

Example:

ARDUINO_VAR_PATH = $(HOME)/sketchbook/hardware/arduino-tiny/cores/tiny

Requirement: Optional

CORE

Description:

Name of the core inside the ALTERNATE_CORE or the standard core.

Usually can be auto-detected as build.core from boards.txt.

Example:

# standard Arduino core (undefine ALTERNATE_CORE)
CORE = arduino
# or
CORE = robot
# tiny core (ALTERNATE_CORE = arduino-tiny)
CORE = tiny

Requirement: Optional

VARIANT

Description:

Variant of a standard board design.

Usually can be auto-detected as build.variant from boards.txt.

Example:

VARIANT = leonardo

Requirement: Optional

USB_TYPE

Description:

Define Teensy 3.1 usb device type. Default is USB_SERIAL

Example:

USB_TYPE = USB_SERIAL
# or
USB_TYPE = USB_HID
# or
USB_TYPE = USB_SERIAL_HID
# or
USB_TYPE = USB_MIDI
# or
USB_TYPE = USB_RAWHID
# or
USB_TYPE = USB_FLIGHTSIM

Requirement: Optional

USB_VID

Description:

Override USB VID for atmega32u4 boards.

Usually can be auto-detected as build.vid from boards.txt

Example:

USB_VID = 0x2341

Requirement: Optional

USB_PID

Description:

Override USB PID for atmega32u4 boards.

Usually can be auto-detected as build.pid from boards.txt

Example:

USB_PID = 0x8039

Requirement: Optional

F_CPU

Description:

CPU speed in Hz

Usually can be auto-detected as build.f_cpu from boards.txt, except in some 1.5+ cores like attiny where there is a clock submenu.

Example:

F_CPU = 8000000L

Requirement: Optional

HEX_MAXIMUM_SIZE

Description:

Maximum hex file size

Usually can be auto-detected as upload.maximum_size from boards.txt

Example:

HEX_MAXIMUM_SIZE = 14336

Requirement: Optional

MCU

Description:

Microcontroller model.

Usually can be auto-detected as build.mcu from boards.txt

Example:

MCU = atmega32u4

Requirement: Optional

MCU_FLAG_NAME

Description:

Override default MCU flags.

Defaults to mmcu

Example:

MCU_FLAG_NAME = mprocessor

Requirement: Optional

MONITOR_BAUDRATE

Description:

Baudrate of the serial monitor.

Defaults to 9600 if it can't find it in the sketch Serial.begin()

Example:

MONITOR_BAUDRATE = 57600

Requirement: Optional

ISP programming variables

ISP_PROG

Description:

Type of ISP. Either a USB device or ArduinoISP protocol.

Example:

ISP_PROG = usbasp
# or
ISP_PROG = usbtiny
# or
ISP_PROG = stk500v2
# or
ISP_PROG = stk500v1

Requirement: Optional

ISP_PORT

Description:

Device path to ArduinoISP. Not needed for hardware ISP's.

Example:

# Linux
ISP_PORT = /dev/ttyACM0

Requirement: Optional

ISP_LOCK_FUSE_PRE

Description:

Bootloader unlock bits.

Usually can be auto-detected from boards.txt

Example:

ISP_LOCK_FUSE_PRE = 0x3f

Requirement: Optional

ISP_LOCK_FUSE_POST

Description:

Bootloader lock bits.

Usually can be auto-detected from boards.txt

Example:

ISP_LOCK_FUSE_POST = 0xcf

Requirement: Optional

ISP_HIGH_FUSE

Description:

ISP_LOW_FUSE/ISP_EXT_FUSE - high/low/extended fuse bits.

Usually can be auto-detected from boards.txt

Example:

ISP_HIGH_FUSE = 0xdf # or 0xff or 0x01

Requirement: Optional

ISP_EEPROM

Description:

Whether to upload the EEPROM file or not.

Defaults to 0

Example:

ISP_EEPROM = 1

Requirement: Optional

Compiler/Executable variables

CC_NAME

Description:

C compiler.

Defaults to avr-gcc

Example:

CC_NAME = pic32-gcc

Requirement: Optional

CXX_NAME

Description:

C++ compiler.

Defaults to avr-g++

Example:

CXX_NAME = pic32-g++

Requirement: Optional

OBJCOPY_NAME

Description:

Objcopy utility.

Defaults to avr-objcopy

Example:

OBJCOPY_NAME = pic32-objcopy

Requirement: Optional

OBJDUMP_NAME

Description:

Objdump utility.

Defaults to avr-objdump

Example:

OBJDUMP_NAME = pic32-objdump

Requirement: Optional

AR_NAME

Description:

Archive utility.

Defaults to avr-ar unless you're using toolchain > 4.9.0 in which case we use avr-gcc-ar.

Example:

AR_NAME = pic32-ar

Requirement: Optional

SIZE_NAME

Description:

Size utility.

Defaults to avr-size

Example:

SIZE_NAME = pic32-size

Requirement: Optional

NM_NAME

Description:

Nm utility.

Defaults to avr-nm

Example:

NM_NAME = pic32-nm

Requirement: Optional

OPTIMIZATION_LEVEL

Description:

Linker's -O flag

Defaults to s, which shouldn't really be changed as it breaks SoftwareSerial and usually results in bigger hex files.

Example:

OPTIMIZATION_LEVEL = 3

Requirement: Optional

OTHER_LIBS

Description:

Additional Linker lib flags, for platform support

Defaults to ""

Example:

OTHER_LIBS = -lsomeplatformlib

Requirement: Optional

CFLAGS_STD

Description:

Controls, exclusively, which C standard is to be used for compilation.

Defaults to undefined on 1.0.x or -std=gnu11 -flto -fno-fat-lto-objects on 1.5+ or if you install AVR toolchain > 4.9.0

Possible values:

With avr-gcc 4.3, shipped with the 1.0 Arduino IDE:
- undefined
- -std=c99
- -std=gnu89 - This is the default for C code
- -std=gnu99
With avr-gcc 4.7, 4.8 or 4.9, installed by you or 1.5+ IDE:
- undefined
- -std=c99
- -std=c11
- -std=gnu89
- -std=gnu99
- -std=gnu11 -flto -fno-fat-lto-objects - This is the default for C code

For more information, please refer to the Options Controlling C Dialect

Example:

CFLAGS_STD = = -std=gnu89

Requirement: Optional

CXXFLAGS_STD

Description:

Controls, exclusively, which C++ standard is to be used for compilation.

Defaults to undefined on 1.0 or -std=gnu++11 -fno-threadsafe-statics -flto on AVR toolchain > 4.9.0 (e.g. IDE 1.6.10+)

Possible values:

With avr-gcc 4.3, shipped with the 1.0 Arduino IDE:
- undefined
- -std=c++98
- -std=c++0x
- -std=gnu++98 - This is the default for C code
- -std=gnu++0x
With avr-gcc 4.7, 4.8 or 4.9, installed by you or 1.5+ IDE:
- undefined
- -std=c++98
- -std=c++11
- -std=c++1y
- -std=c++14
- -std=gnu++98
- -std=gnu++11 -fno-threadsafe-statics -flto - This is the default for C++ code
- -std=gnu++1y
- -std=gnu++14

For more information, please refer to the Options Controlling C Dialect

Example:

CXXFLAGS_STD = = -std=gnu++98

Requirement: Optional

CFLAGS

Description:

Flags passed to compiler for files compiled as C. Add more flags to this variable using +=.

Defaults to all flags required for a typical build.

Example:

CFLAGS += -my-c-only-flag

Requirement: Optional

CXXFLAGS

Description:

Flags passed to the compiler for files compiled as C++. Add more flags to this variable using +=.

Defaults to -fpermissive -fno-exceptions

Example:

CXXFLAGS += -my-c++-onlyflag

Requirement: Optional

ASFLAGS

Description:

Flags passed to compiler for files compiled as assembly (e.g. .S files). Add more flags to this variable using +=.

Defaults to all flags required for a typical build.

Example:

ASFLAGS += -my-as-only-flag

Requirement: Optional

CPPFLAGS

Description:

Flags passed to the C pre-processor (for C, C++ and assembly source flies). Add more flags to this variable using +=.

Defaults to all flags required for a typical build.

Example:

CPPFLAGS += -DMY_DEFINE_FOR_ALL_SOURCE_TYPES

Requirement: Optional

OVERRIDE_EXECUTABLES

Description:

Override the default build tools.

If set to 1, each tool (CC, CXX, AS, OBJCOPY, OBJDUMP, AR, SIZE, NM) must have its path explicitly defined. See chipKIT.mk.

Example:

OVERRIDE_EXECUTABLES = 1

Requirement: Optional

MONITOR_CMD

Description:

Command to run the serial monitor.

Defaults to screen

Example:

MONITOR_CMD = minicom

Requirement: Optional

PRE_BUILD_HOOK

Description:

Path to shell script to be executed before build. Could be used to automatically bump revision number for example.

Defaults to pre-build-hook.sh

Example:

PRE_BUILD_HOOK = $(HOME)/bin/bump-revision.sh

Requirement: Optional

Avrdude setting variables

AVRDUDE

Description:

Path to avrdude utility

Usually can be auto-detected within the parent of AVR_TOOLS_DIR or in the $PATH

Example:

AVRDUDE = /usr/bin/avrdude

Requirement: Optional

AVRDUDE_CONF

Description:

Path to avrdude.conf file

Usually can be auto-detected within the parent of AVR_TOOLS_DIR

Example:

AVRDUDE_CONF = /etc/avrdude.conf
# or
AVRDUDE_CONF = /usr/share/arduino/hardware/tools/avrdude.conf

Requirement: Optional

AVR_TOOLS_PATH

Description:

Directory where tools such as avrdude, avr-g++, avr-gcc etc. are stored.

Usually can be auto-detected from AVR_TOOLS_DIR/bin

Example:

AVR_TOOLS_PATH = /usr/bin
# or
AVR_TOOLS_PATH = /usr/share/arduino/hardware/tools/avr/bin

Requirement: Optional

ARDUINO_LIB_PATH

Description:

Directory where the standard Arduino libraries are stored.

Defaults to ARDUINO_DIR/libraries

Example:

# Linux
ARDUINO_LIB_PATH = /usr/share/arduino/libraries

Requirement: Optional

ARDUINO_CORE_PATH

Description:

Directory where the standard Arduino cores are stored.

Defaults to ARDUINO_DIR/hardware/arduino/cores/arduino

Example:

ARDUINO_CORE_PATH = /usr/share/arduino/hardware/arduino/cores/robot

Requirement: Optional

ALTERNATE_CORE_PATH

Description:

Path to non-standard cores.

Defaults to ARDUINO_SKETCHBOOK/hardware/ALTERNATE_CORE

Example:

ALTERNATE_CORE_PATH = $(HOME)/sketchbook/hardware/arduino-tiny/cores/tiny

Requirement: Optional

BOARDS_TXT

Description:

Path to boards.txt

Defaults to ARDUINO_DIR/hardware/arduino/boards.txt

Example:

BOARD_TXT = $(HOME)/sketchbook/hardware/boards.txt
# or
BOARD_TXT = /usr/share/arduino/hardware/arduino/boards.txt

Requirement: Optional

AVRDUDE_ARD_BAUDRATE

Description:

Upload speed

Usually can be auto-detected as upload.speed from boards.txt

Example:

AVRDUDE_ARD_BAUDRATE = 19200

Requirement: Optional

AVRDUDE_ARD_PROGRAMMER

Description:

Upload protocol

Usually can be auto-detected as upload.protocol from boards.txt

Example:

AVRDUDE_ARD_PROGRAMMER = stk500v1

Requirement: Optional

AVRDUDE_ISP_BAUDRATE

Description:

ISP speed if different to upload.speed

Defaults to same as AVRDUDE_ARD_BAUDRATE or 19200

Example:

AVRDUDE_ISP_BAUDRATE = 19200

Requirement: Optional

AVRDUDE_OPTS

Description:

Options to pass to avrdude.

Defaults to -q -V (quiet, don't verify). User values are not ANDed to the defaults, you have to set each option you require.

Example:

AVRDUDE_OPTS = -v

Requirement: Optional

Bootloader variables

BOOTLOADER_FILE

Description:

File for bootloader.

Usually can be auto-detected as bootloader.file from boards.txt

Example:

BOOTLOADER_FILE = optiboot_atmega328.hex

Requirement: Optional

BOOTLOADER_PATH

Description:

Relative path to bootloader directory.

Usually can be auto-detected as a relative bootloader.path from boards.txt

Deprecated in 1.5, now part of bootloader.file

Example:

BOOTLOADER_PATH = optiboot
# or
BOOTLOADER_PATH = arduino:atmega

Requirement: Optional

BOOTLOADER_PARENT

Description:

Absolute path to bootloader file's parent directory.

Defaults to /usr/share/arduino/hardware/arduino/bootloaders (Linux)

Example:

BOOTLOADER_PARENT = $(HOME)/sketchbook/hardware/promicro/bootloaders
BOOTLOADER_PATH  = caterina
BOOTLOADER_FILE  = Caterina-promicro16.hex

Would result in an absolute path to the bootloader hex file of $(HOME)/sketchbook/hardware/promicro/bootloaders/caterina/Caterina-promicro16.hex

Requirement: Optional, unless BOOTLOADER_FILE and/or BOOTLOADER_PATH are user-defined

ChipKIT variables

MPIDE_DIR

Description:

Path to chipKIT MP IDE

Usually can be auto-detected as AUTO_MPIDE_DIR from the defaults /usr/share/mpide (Linux) or /Applications/Mpide.app/Contents/Resources/Java (OSX)

Example:

MPIDE_DIR = $(HOME)/mpide

Requirement: Optional

Ctags variables

TAGS_FILE

Description:

Output file name for tags. Defaults to 'tags'.

Example:

TAGS_FILE = .tags

Requirement: Optional

CTAGS_OPTS

Description:

Additional options to pass to ctags command.

Example:

# Run ctags in verbose mode
CTAGS_OPTS = -V

Requirement: Optional

CTAGS_CMD

Description:

Location of ctags binary. Defaults to user path.

Example:

CTAGS_CMD = /usr/local/bin/

Requirement: Optional

MPIDE_PREFERENCES_PATH

Description:

Path to chipKIT preferences.txt file.

Usually can be auto-detected as AUTO_MPIDE_PREFERENCES_PATH from the defaults $(HOME)/.mpide/preferences.txt (Linux) or $(HOME)/Library/Mpide/preferences.txt (OSX)

Example:

MPIDE_PREFERENCES_PATH = $(HOME)/chipkit/preferences.txt

Requirement: Optional

21 KiB Raw Blame History

Documentation of variables

Global variables

ARDUINO_QUIET

Installation/Directory variables

ARDMK_DIR

AVR_TOOLS_DIR

RESET_CMD

Arduino IDE variables

ARDUINO_DIR

ARDUINO_PLATFORM_LIB_PATH

ARDUINO_VERSION

ARCHITECTURE

ARDMK_VENDOR

ARDUINO_SKETCHBOOK

ARDUINO_PREFERENCES_PATH

ARDUINO_CORE_PATH

Sketch related variables

ARDUINO_LIBS

BOARD_TAG

BOARD_SUB

MONITOR_PORT

FORCE_MONITOR_PORT

USER_LIB_PATH

OBJDIR

TARGET

ALTERNATE_CORE

ARDUINO_VAR_PATH

CORE

VARIANT

USB_TYPE

USB_VID

USB_PID

F_CPU

HEX_MAXIMUM_SIZE

MCU

MCU_FLAG_NAME

MONITOR_BAUDRATE

ISP programming variables

ISP_PROG

ISP_PORT

ISP_LOCK_FUSE_PRE

ISP_LOCK_FUSE_POST

ISP_HIGH_FUSE

ISP_EEPROM

Compiler/Executable variables

CC_NAME

CXX_NAME

OBJCOPY_NAME

OBJDUMP_NAME

AR_NAME

SIZE_NAME

NM_NAME

OPTIMIZATION_LEVEL

OTHER_LIBS

CFLAGS_STD

CXXFLAGS_STD

CFLAGS

CXXFLAGS

ASFLAGS

CPPFLAGS

OVERRIDE_EXECUTABLES

MONITOR_CMD

PRE_BUILD_HOOK

Avrdude setting variables

AVRDUDE

AVRDUDE_CONF

AVR_TOOLS_PATH

ARDUINO_LIB_PATH

ARDUINO_CORE_PATH

ALTERNATE_CORE_PATH

BOARDS_TXT

AVRDUDE_ARD_BAUDRATE

AVRDUDE_ARD_PROGRAMMER

AVRDUDE_ISP_BAUDRATE

AVRDUDE_OPTS

Bootloader variables

BOOTLOADER_FILE

BOOTLOADER_PATH

BOOTLOADER_PARENT

21 KiB

Raw Blame History