mirror of
https://github.com/arduino/Arduino.git
synced 2024-12-04 15:24:12 +01:00
24029c5ace
* CLI: Add --version to CLI option I added to get the Arduino IDE version from the command line It will allow to check easily if the new Arduino is already installed. This feature makes it easier to build external systems linked to specific versions of Arduino. 1. I added `--version` action, which shows version name and exit 1. Currently, VERSION_NAME_LONG (like `1.8.5`, `1.9.0-beta`, `1.8.6 Hourly Build XXX`, etc...) is used. Because I want to know its version number and stable/beta/hourly. 2. Finish with `0`. Because it is `SUCCESSFLLY FINISHED`. 2. Updated man page. * Split "parse" and "action". Move print action to probably suitable place. This commit will fix the behavior of multiple actions about --version. * add testcase
347 lines
12 KiB
Plaintext
347 lines
12 KiB
Plaintext
// Generate a manpage with: a2x -f manpage manpage.adoc
|
|
// or HTML with: a2x -f xhtml manpage.adoc
|
|
//
|
|
// This file uses {empty}:: in some places, to allow putting multiple
|
|
// paragraphs inside a single label list item. This is a bit ugly and
|
|
// non-semantic, but it seems this is the best way to do this. Asciidoc
|
|
// also supports putting a plus sign on a line by itself to join two
|
|
// paragraphs into a single list item. However, the indentation on the
|
|
// second paragraph makes that formatted with a fixed-size font.
|
|
// Removing the indentation completely makes the asciidoc source very
|
|
// unreadable. Also, for the --board option, there is a a paragraph,
|
|
// followed by a list, followed by another paragraph. The + approach can
|
|
// only put the latter paragraph into the inner list, not the outer
|
|
// one...
|
|
|
|
ARDUINO(1)
|
|
==========
|
|
:doctype: manpage
|
|
|
|
NAME
|
|
----
|
|
arduino - Integrated development environment for Arduino boards
|
|
|
|
SYNOPSIS
|
|
--------
|
|
*arduino* ['FILE.ino'...]
|
|
|
|
*arduino* [*--verify*|*--upload*] [*--board* __package__:__arch__:__board__[:__parameters__]] [*--port* __portname__] [*--pref* __name__=__value__] [*-v*|*--verbose*] [*--preserve-temp-files*] [__FILE.ino__]
|
|
|
|
*arduino* [*--get-pref* [__preference__]]
|
|
|
|
*arduino* [*--install-boards* __package name__:__platform architecture__[:__version__]]
|
|
|
|
*arduino* [*--install-library* __library name__[:__version__][,__library name__[:__version__],__library name__[:__version__]]
|
|
|
|
*arduino* [*--version*]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
The 'arduino' integrated development environment allows editing,
|
|
compiling and uploading sketches (programs) for Arduino
|
|
(and compatible) microcontroller boards.
|
|
|
|
Normally, running the arduino command starts the IDE, optionally loading
|
|
any .ino files specified on the commandline.
|
|
|
|
Alternatively, if any of the following command line options is given, no graphical
|
|
interface will be shown and instead a one-off verify (compile) or upload
|
|
will be done. A single .ino file should be given. If the sketch contains
|
|
multiple .ino files, any one can be specified on the commandline, but
|
|
the entire sketch will be compiled.
|
|
|
|
When running in a one-off mode, it might be useful to set the
|
|
*build.path* preference to allow keeping intermediate build results
|
|
between multiple runs and only recompile the files that changed.
|
|
|
|
Note that on MacOS X, the main executable is
|
|
'Arduino.app/Contents/MacOS/Arduino' instead of 'arduino'.
|
|
|
|
Note that on Windows, due to the diffence between GUI and console apps, that the
|
|
'arduino_debug.exe' is the appropriate executable to use if you want to use the majority
|
|
of these command line options. The 'arduino.exe' GUI version of the launcher **may** perform
|
|
some of the functions described below, but will not output any messages to the console,
|
|
meaning it is pretty useless if you want any feedback or to be able to keep log files for
|
|
automated testing, etc.
|
|
|
|
ACTIONS
|
|
|
|
*--verify*::
|
|
Build the sketch.
|
|
|
|
*--upload*::
|
|
Build and upload the sketch.
|
|
|
|
*--get-pref* [__preference__]::
|
|
Prints the value of the given preference to the standard output
|
|
stream. When the value does not exist, nothing is printed and
|
|
the exit status is set (see EXIT STATUS below).
|
|
If no preference is given as parameter, it prints all preferences.
|
|
|
|
*--install-boards* __package name__:__platform architecture__[:__version__]::
|
|
Fetches available board support (platform) list and install the specified one, along with its related tools. If __version__ is omitted, the latest is installed. If a platform with the same version is already installed, nothing is installed and program exits with exit code 1. If a platform with a different version is already installed, it's replaced.
|
|
|
|
*--install-library* __library name__[:__version__]::
|
|
Fetches available libraries list and install the specified one. If __version__ is omitted, the latest is installed. If a library with the same version is already installed, nothing is installed and program exits with exit code 1. If a library with a different version is already installed, it's replaced.
|
|
Multiple libraries can be specified, separated by a comma.
|
|
|
|
*--version*::
|
|
Print the version information and exit.
|
|
|
|
OPTIONS
|
|
-------
|
|
*--board* __package__:__arch__:__board__[:__parameters__]::
|
|
Select the board to compile for.
|
|
|
|
* __package__ is the identifier of the vendor (the first
|
|
level folders inside the 'hardware' directory). Default
|
|
arduino boards use 'arduino'.
|
|
* __architecture__ is the architecture of the board (second level folders
|
|
inside the 'hardware' directory). Default arduino boards use
|
|
either *arduino:avr* for all AVR-based boards (like Uno, Mega
|
|
or Leonardo) or *arduino:sam* for 32bit SAM-based boards
|
|
(like Arduino Due).
|
|
* __board__ is the actual board to use, as defined in 'boards.txt'
|
|
contained in the architecture folder selected. For example,
|
|
*arduino:avr:uno* for the Arduino Uno,
|
|
*arduino:avr:diecimila* for the Arduino Duemilanove or
|
|
Diecimila, or *arduino:avr:mega* for the Arduino Mega.
|
|
* __parameters__ is a comma-separated list of boards specific parameters
|
|
that are normally shown under submenus of the "Tools" menu. For
|
|
example *arduino:avr:nano:cpu=atmega168* to Select the mega168
|
|
variant of the Arduino Nano board.
|
|
|
|
{empty}::
|
|
If this option is not passed, the value from the current
|
|
preferences is used (e.g., the last board selected in the IDE).
|
|
|
|
*--port* __portname__::
|
|
Select the serial port to perform upload of the sketch.
|
|
On linux and MacOS X, this should be the path to a device file (e.g.,
|
|
*/dev/ttyACM0*). On Windows, this should be the name of the serial
|
|
port (e.g., *COM3*).
|
|
|
|
{empty}::
|
|
If this option is not passed, the value from the current
|
|
preferences is used (e.g., the last port selected in the IDE).
|
|
|
|
*--verbose-build*::
|
|
Enable verbose mode during build. If this option is not given,
|
|
verbose mode during build is *disabled* regardless of the current
|
|
preferences.
|
|
|
|
*--preserve-temp-files*::
|
|
Keep temporary files (preprocessed sketch, object files...) after termination.
|
|
If omitted, temporary files are deleted.
|
|
|
|
{empty}::
|
|
This option is only valid together with *--verify* or
|
|
*--upload*.
|
|
|
|
*--useprogrammer*::
|
|
Upload using a programmer. Set if you're using an external programmer, or
|
|
using the Arduino as ISP.
|
|
|
|
*--verbose-upload*::
|
|
Enable verbose mode during upload. If this option is not given,
|
|
verbose mode during upload is *disabled* regardless of the current
|
|
preferences.
|
|
|
|
{empty}::
|
|
This option is only valid together with *--verify* or
|
|
*--upload*.
|
|
|
|
*-v, --verbose*::
|
|
Enable verbose mode during build and upload.
|
|
This option has the same effect of using both *--verbose-build*
|
|
and *--verbose-upload*.
|
|
|
|
{empty}::
|
|
This option is only valid together with *--verify* or
|
|
*--upload*.
|
|
|
|
*--preferences-file* __filename__::
|
|
Read and store preferences from the specified __filename__ instead
|
|
of the default one.
|
|
|
|
*--pref* __name__=__value__::
|
|
Sets the preference __name__ to the given __value__.
|
|
|
|
{empty}::
|
|
Note that the preferences you set with this option are not
|
|
validated: Invalid names will be set but never used, invalid
|
|
values might lead to an error later on.
|
|
|
|
*--save-prefs*::
|
|
Save any (changed) preferences to *preferences.txt*. In particular
|
|
*--board*, *--port*, *--pref*, *--verbose*, *--verbose-build* and
|
|
*--verbose-upload* may alter the current preferences.
|
|
|
|
PREFERENCES
|
|
-----------
|
|
Arduino keeps a list of preferences, as simple name and value pairs.
|
|
Below, a few of them are documented but a lot more are available.
|
|
|
|
*sketchbook.path*::
|
|
The path where sketches are (usually) stored. This path can also
|
|
contain some special subdirectories (see FILES below).
|
|
|
|
*update.check*::
|
|
When set to true, the IDE checks for a new version on startup.
|
|
|
|
*editor.external*::
|
|
When set to true, use an external editor (the IDE does not allow
|
|
editing and reloads each file before verifying).
|
|
|
|
*build.path*::
|
|
The path to use for building. This is where things like the
|
|
preprocessed .cpp file, compiled .o files and the final .hex
|
|
file go.
|
|
|
|
{empty}::
|
|
If set, this directory should already exist before running the
|
|
arduino command.
|
|
|
|
{empty}::
|
|
If this preference is not set (which is normally the case), a
|
|
new temporary build folder is created on every run and deleted
|
|
again when the application is closed.
|
|
|
|
EXIT STATUS
|
|
-----------
|
|
*0*:: Success
|
|
*1*:: Build failed or upload failed
|
|
*2*:: Sketch not found
|
|
*3*:: Invalid (argument for) commandline option
|
|
*4*:: Preference passed to *--get-pref* does not exist
|
|
|
|
FILES
|
|
-----
|
|
*%LOCALAPPDATA%/Arduino15/preferences.txt* (Windows)::
|
|
*~/Library/Arduino15/preferences.txt* (Max OS X)::
|
|
*~/.arduino15/preferences.txt* (Linux)::
|
|
This file stores the preferences used for the IDE, building and
|
|
uploading sketches.
|
|
|
|
*My Documents/Arduino/* (Windows)::
|
|
*~/Documents/Arduino/* (Mac OS X)::
|
|
*~/Arduino/* (Linux)::
|
|
This directory is referred to as the "Sketchbook" and contains
|
|
the user's sketches. The path can be changed through the
|
|
*sketchbook.path* preference.
|
|
|
|
{empty}::
|
|
Apart from sketches, three special directories can be inside the
|
|
sketchbook:
|
|
|
|
*libraries*:::
|
|
Libraries can be put inside this directory, one library
|
|
per subdirectory.
|
|
|
|
*hardware*:::
|
|
Support for third-party hardware can be added through
|
|
this directory.
|
|
|
|
*tools*:::
|
|
External code-processing tools (that can be run through
|
|
the Tools menu of the IDE) can be added here.
|
|
|
|
EXAMPLES
|
|
--------
|
|
|
|
Start the Arduino IDE, with two files open:
|
|
|
|
arduino /path/to/sketch/sketch.ino /path/to/sketch/extra.ino
|
|
|
|
Compile and upload a sketch using the last selected board and serial port
|
|
|
|
arduino --upload /path/to/sketch/sketch.ino
|
|
|
|
Compile and upload a sketch to an Arduino Nano, with an Atmega168 CPU,
|
|
connected on port '/dev/ttyACM0':
|
|
|
|
arduino --board arduino:avr:nano:cpu=atmega168 --port /dev/ttyACM0 --upload /path/to/sketch/sketch.ino
|
|
|
|
Compile a sketch, put the build results in the 'build' directory an
|
|
re-use any previous build results in that directory.
|
|
|
|
arduino --pref build.path=/path/to/sketch/build --verify /path/to/sketch/sketch.ino
|
|
|
|
Change the selected board and build path and do nothing else.
|
|
|
|
arduino --pref build.path=/path/to/sketch/build --board arduino:avr:uno --save-prefs
|
|
|
|
Install latest SAM board support
|
|
|
|
arduino --install-boards "arduino:sam"
|
|
|
|
Install AVR board support, 1.6.2
|
|
|
|
arduino --install-boards "arduino:avr:1.6.2"
|
|
|
|
Install Bridge library version 1.0.0
|
|
|
|
arduino --install-library "Bridge:1.0.0"
|
|
|
|
Install Bridge and Servo libraries
|
|
|
|
arduino --install-library "Bridge:1.0.0,Servo:1.2.0"
|
|
|
|
HISTORY
|
|
-------
|
|
1.5.2::
|
|
Added initial commandline support. This introduced *--verify*,
|
|
*--upload*, *--board*, *--port*, *--verbose* and *-v*.
|
|
|
|
1.5.5::
|
|
Added support for board-specific parameters to *--board*.
|
|
|
|
{empty}::
|
|
Sketch filenames are now interpreted relative to the current
|
|
directory instead of the location of the arduino command itself.
|
|
|
|
1.5.6::
|
|
Introduced *--pref*, *--preferences-file*, *--verbose-build* and
|
|
*--verbose-upload*.
|
|
|
|
{empty}::
|
|
Preferences set through --pref are remembered, preferences set
|
|
through *--board*, *--port* or the *--verbose* options are not.
|
|
|
|
{empty}::
|
|
When running with *--verify* or *--upload*, the full GUI is no
|
|
longer shown. Error messages still use a graphical popup and on
|
|
Windows, the splash screen is still shown.
|
|
|
|
1.5.8::
|
|
Introduced *--save-prefs*.
|
|
|
|
1.6.2::
|
|
Main executable in MacOS X changed from
|
|
'Arduino.app/Contents/MacOS/JavaApplicationStub' to
|
|
'Arduino.app/Contents/MacOS/Arduino'.
|
|
|
|
1.6.4::
|
|
Introduced *--install-boards* and *--install-library*.
|
|
|
|
{empty}::
|
|
*--pref* options are now not saved to the preferences file, just
|
|
like *--board* and *--port*, unless *--save-prefs* is specified.
|
|
|
|
{empty}::
|
|
A path passed to *--preferences-file*, or set in the
|
|
*build.path*, *preferences.path* or *settings.path* is now
|
|
interpreted relative to the current directory instead of the
|
|
location of the arduino command itself.
|
|
|
|
|
|
RESOURCES
|
|
---------
|
|
Web site: <http://www.arduino.cc/>
|
|
|
|
Help on projects and programming: <http://forum.arduino.cc/>
|
|
|
|
Report bugs: <http://github.com/arduino/Arduino/issues>
|
|
|
|
IDE and framework development mailing list: <https://groups.google.com/a/arduino.cc/forum/#!forum/developers>
|