rooty/Arduino
1
0
Fork 0
mirror of https://github.com/arduino/Arduino.git synced 2024-11-29 10:24:12 +01:00
Code Issues Releases Activity
e3dc5e75e3
Arduino/build/shared/manpage.adoc

299 lines
9.8 KiB
Plaintext
Raw Normal View History

Add manual page This adds a description of commandline options, files used and some preferences in proper Unix manpage format. It is written in asciidoc, which can easily be converted to both a native troff manpage, or HTML (the latter can be done by github on-demand).
2013-12-09 10:45:24 +01:00
// 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*] [__FILE.ino__]
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 *--verify* or *--upload* 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/JavaApplicationStub' instead of 'arduino'.
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).
Process some commandline arguments earlier Previously, the --board and --port arguments were stored in a variable first and only processed later. Now, the arguments are processed right away. This does mean that the arguments are processed when the GUI is not yet initialized, which caused problems with calling onBoardOrPortChange and friends from selectBoard. However, since the GUI is not initialized, there is no real reason to call them either - if we just set the preferences to the right values, the GUI will be initialized correctly later. For this reason, selectBoard no longer calls the GUI update methods. Instead, those are called from the GUI code when the board is changed through the menu instead (e.g., after calling selectBoard). This commit slightly changes behaviour. Previously, --board and --port only worked in combination with --verify and --upload, but were ignored when just starting the IDE. Now, these are processed regardless of the other options present. Additionally, this commit causes all changed preferences to be saved. Previously, only changes with --pref were saved, --board and --port options were only active for the current run. This was caused because the saving of the preferences happened as a side effect of loading the file in the Editor, but only the --pref option was processed at that time. Note that the --verbose options are still only active for the current run and are only valid combined with --verify or --upload (since they default to non-verbose instead of the current preference).
2014-04-07 10:27:39 +02:00
If this option is given, the value passed is written to the
Add --no-save-prefs option This allows setting preferences for the current run only, without remembering them for the next run. This is especially useful when combined with --verify or --upload.
2014-04-07 10:40:45 +02:00
preferences file and rememberd for subsequent runs (except when
*--no-save-prefs* is passed).
Add manual page This adds a description of commandline options, files used and some preferences in proper Unix manpage format. It is written in asciidoc, which can easily be converted to both a native troff manpage, or HTML (the latter can be done by github on-demand).
2013-12-09 10:45:24 +01:00
*--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).
Process some commandline arguments earlier Previously, the --board and --port arguments were stored in a variable first and only processed later. Now, the arguments are processed right away. This does mean that the arguments are processed when the GUI is not yet initialized, which caused problems with calling onBoardOrPortChange and friends from selectBoard. However, since the GUI is not initialized, there is no real reason to call them either - if we just set the preferences to the right values, the GUI will be initialized correctly later. For this reason, selectBoard no longer calls the GUI update methods. Instead, those are called from the GUI code when the board is changed through the menu instead (e.g., after calling selectBoard). This commit slightly changes behaviour. Previously, --board and --port only worked in combination with --verify and --upload, but were ignored when just starting the IDE. Now, these are processed regardless of the other options present. Additionally, this commit causes all changed preferences to be saved. Previously, only changes with --pref were saved, --board and --port options were only active for the current run. This was caused because the saving of the preferences happened as a side effect of loading the file in the Editor, but only the --pref option was processed at that time. Note that the --verbose options are still only active for the current run and are only valid combined with --verify or --upload (since they default to non-verbose instead of the current preference).
2014-04-07 10:27:39 +02:00
If this option is given, the value passed is written to the
Add --no-save-prefs option This allows setting preferences for the current run only, without remembering them for the next run. This is especially useful when combined with --verify or --upload.
2014-04-07 10:40:45 +02:00
preferences file and rememberd for subsequent runs (except when
*--no-save-prefs* is passed).
Add manual page This adds a description of commandline options, files used and some preferences in proper Unix manpage format. It is written in asciidoc, which can easily be converted to both a native troff manpage, or HTML (the latter can be done by github on-demand).
2013-12-09 10:45:24 +01:00
Added command line option --verbose-build and --verbose-upload
2014-02-06 13:34:33 +01:00
*--verbose-build*::
Fix indentation in the manpage
2014-04-07 11:26:29 +02:00
Enable verbose mode during build. If this option is not given,
verbose mode during build is disabled regardless of the current
preferences.
Added command line option --verbose-build and --verbose-upload
2014-02-06 13:34:33 +01:00
Error when passing --verbose without --verify or --upload Since the handling of these options defaults to non-verbose (instead of the current preference), they make no sense when starting the IDE normally. Previously, these options would just be ignored in this case, now an error is shown.
2014-04-07 11:47:04 +02:00
{empty}::
This option is only valid together with *--verify* or
*--upload*.
Added command line option --verbose-build and --verbose-upload
2014-02-06 13:34:33 +01:00
*--verbose-upload*::
Fix indentation in the manpage
2014-04-07 11:26:29 +02:00
Enable verbose mode during upload. If this option is not given,
verbose mode during upload is disabled regardless of the current
preferences.
Add manual page This adds a description of commandline options, files used and some preferences in proper Unix manpage format. It is written in asciidoc, which can easily be converted to both a native troff manpage, or HTML (the latter can be done by github on-demand).
2013-12-09 10:45:24 +01:00
Error when passing --verbose without --verify or --upload Since the handling of these options defaults to non-verbose (instead of the current preference), they make no sense when starting the IDE normally. Previously, these options would just be ignored in this case, now an error is shown.
2014-04-07 11:47:04 +02:00
{empty}::
This option is only valid together with *--verify* or
*--upload*.
Added command line option --verbose-build and --verbose-upload
2014-02-06 13:34:33 +01:00
*-v, --verbose*::
Enable verbose mode during build and upload.
Fix indentation in the manpage
2014-04-07 11:26:29 +02:00
This option has the same effect of using both *--verbose-build*
and *--verbose-upload*.
Add manual page This adds a description of commandline options, files used and some preferences in proper Unix manpage format. It is written in asciidoc, which can easily be converted to both a native troff manpage, or HTML (the latter can be done by github on-demand).
2013-12-09 10:45:24 +01:00
Error when passing --verbose without --verify or --upload Since the handling of these options defaults to non-verbose (instead of the current preference), they make no sense when starting the IDE normally. Previously, these options would just be ignored in this case, now an error is shown.
2014-04-07 11:47:04 +02:00
{empty}::
This option is only valid together with *--verify* or
*--upload*.
Updated manpage
2014-01-25 23:29:35 +01:00
*--preferences-file* __filename__::
Read and store preferences from the specified __filename__ instead
of the default one.
Add manual page This adds a description of commandline options, files used and some preferences in proper Unix manpage format. It is written in asciidoc, which can easily be converted to both a native troff manpage, or HTML (the latter can be done by github on-demand).
2013-12-09 10:45:24 +01:00
*--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.
Process some commandline arguments earlier Previously, the --board and --port arguments were stored in a variable first and only processed later. Now, the arguments are processed right away. This does mean that the arguments are processed when the GUI is not yet initialized, which caused problems with calling onBoardOrPortChange and friends from selectBoard. However, since the GUI is not initialized, there is no real reason to call them either - if we just set the preferences to the right values, the GUI will be initialized correctly later. For this reason, selectBoard no longer calls the GUI update methods. Instead, those are called from the GUI code when the board is changed through the menu instead (e.g., after calling selectBoard). This commit slightly changes behaviour. Previously, --board and --port only worked in combination with --verify and --upload, but were ignored when just starting the IDE. Now, these are processed regardless of the other options present. Additionally, this commit causes all changed preferences to be saved. Previously, only changes with --pref were saved, --board and --port options were only active for the current run. This was caused because the saving of the preferences happened as a side effect of loading the file in the Editor, but only the --pref option was processed at that time. Note that the --verbose options are still only active for the current run and are only valid combined with --verify or --upload (since they default to non-verbose instead of the current preference).
2014-04-07 10:27:39 +02:00
{empty}::
If this option is given, the value passed is written to the
Add --no-save-prefs option This allows setting preferences for the current run only, without remembering them for the next run. This is especially useful when combined with --verify or --upload.
2014-04-07 10:40:45 +02:00
preferences file and rememberd for subsequent runs (except when
*--no-save-prefs* is passed).
*--no-save-prefs*::
Do not save any (changed) preferences to *preferences.txt*.
Process some commandline arguments earlier Previously, the --board and --port arguments were stored in a variable first and only processed later. Now, the arguments are processed right away. This does mean that the arguments are processed when the GUI is not yet initialized, which caused problems with calling onBoardOrPortChange and friends from selectBoard. However, since the GUI is not initialized, there is no real reason to call them either - if we just set the preferences to the right values, the GUI will be initialized correctly later. For this reason, selectBoard no longer calls the GUI update methods. Instead, those are called from the GUI code when the board is changed through the menu instead (e.g., after calling selectBoard). This commit slightly changes behaviour. Previously, --board and --port only worked in combination with --verify and --upload, but were ignored when just starting the IDE. Now, these are processed regardless of the other options present. Additionally, this commit causes all changed preferences to be saved. Previously, only changes with --pref were saved, --board and --port options were only active for the current run. This was caused because the saving of the preferences happened as a side effect of loading the file in the Editor, but only the --pref option was processed at that time. Note that the --verbose options are still only active for the current run and are only valid combined with --verify or --upload (since they default to non-verbose instead of the current preference).
2014-04-07 10:27:39 +02:00
Add manual page This adds a description of commandline options, files used and some preferences in proper Unix manpage format. It is written in asciidoc, which can easily be converted to both a native troff manpage, or HTML (the latter can be done by github on-demand).
2013-12-09 10:45:24 +01:00
*--upload*::
Build and upload the sketch.
*--verify*::
Build the sketch.
Add --noop option This option causes the IDE to process its commandline arguments and then quit. This allows setting preferences uses --pref, without having to also load the GUI or compile a sketch.
2014-04-07 12:01:54 +02:00
*--noop*::
Immediately quit after processing the commandline. This can be
used to just set preferences with *--pref*.
Add --get-pref option This allows reading specific preferences from the commandline.
2014-04-07 12:19:22 +02:00
*--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).
Add manual page This adds a description of commandline options, files used and some preferences in proper Unix manpage format. It is written in asciidoc, which can easily be converted to both a native troff manpage, or HTML (the latter can be done by github on-demand).
2013-12-09 10:45:24 +01:00
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
Add --get-pref option This allows reading specific preferences from the commandline.
2014-04-07 12:19:22 +02:00
*4*:: Preference passed to *--get-pref* does not exist
Add manual page This adds a description of commandline options, files used and some preferences in proper Unix manpage format. It is written in asciidoc, which can easily be converted to both a native troff manpage, or HTML (the latter can be done by github on-demand).
2013-12-09 10:45:24 +01:00
FILES
-----
*~/.arduino15/preferences.txt*::
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
Add --noop option This option causes the IDE to process its commandline arguments and then quit. This allows setting preferences uses --pref, without having to also load the GUI or compile a sketch.
2014-04-07 12:01:54 +02:00
Change the selected board and build path and do nothing else.
arduino --pref build.path=/path/to/sketch/build --board arduino:avr:uno --noop
Added history section to the manpage This describes the versions where various options were introduced or changed.
2014-04-07 11:14:08 +02:00
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.
Process some commandline arguments earlier Previously, the --board and --port arguments were stored in a variable first and only processed later. Now, the arguments are processed right away. This does mean that the arguments are processed when the GUI is not yet initialized, which caused problems with calling onBoardOrPortChange and friends from selectBoard. However, since the GUI is not initialized, there is no real reason to call them either - if we just set the preferences to the right values, the GUI will be initialized correctly later. For this reason, selectBoard no longer calls the GUI update methods. Instead, those are called from the GUI code when the board is changed through the menu instead (e.g., after calling selectBoard). This commit slightly changes behaviour. Previously, --board and --port only worked in combination with --verify and --upload, but were ignored when just starting the IDE. Now, these are processed regardless of the other options present. Additionally, this commit causes all changed preferences to be saved. Previously, only changes with --pref were saved, --board and --port options were only active for the current run. This was caused because the saving of the preferences happened as a side effect of loading the file in the Editor, but only the --pref option was processed at that time. Note that the --verbose options are still only active for the current run and are only valid combined with --verify or --upload (since they default to non-verbose instead of the current preference).
2014-04-07 10:27:39 +02:00
1.5.7::
Add --noop option This option causes the IDE to process its commandline arguments and then quit. This allows setting preferences uses --pref, without having to also load the GUI or compile a sketch.
2014-04-07 12:01:54 +02:00
Introduced *--no-save-prefs* and *--noop*.
Add --no-save-prefs option This allows setting preferences for the current run only, without remembering them for the next run. This is especially useful when combined with --verify or --upload.
2014-04-07 10:40:45 +02:00
{empty}::
Process some commandline arguments earlier Previously, the --board and --port arguments were stored in a variable first and only processed later. Now, the arguments are processed right away. This does mean that the arguments are processed when the GUI is not yet initialized, which caused problems with calling onBoardOrPortChange and friends from selectBoard. However, since the GUI is not initialized, there is no real reason to call them either - if we just set the preferences to the right values, the GUI will be initialized correctly later. For this reason, selectBoard no longer calls the GUI update methods. Instead, those are called from the GUI code when the board is changed through the menu instead (e.g., after calling selectBoard). This commit slightly changes behaviour. Previously, --board and --port only worked in combination with --verify and --upload, but were ignored when just starting the IDE. Now, these are processed regardless of the other options present. Additionally, this commit causes all changed preferences to be saved. Previously, only changes with --pref were saved, --board and --port options were only active for the current run. This was caused because the saving of the preferences happened as a side effect of loading the file in the Editor, but only the --pref option was processed at that time. Note that the --verbose options are still only active for the current run and are only valid combined with --verify or --upload (since they default to non-verbose instead of the current preference).
2014-04-07 10:27:39 +02:00
*--board* and *--port* options are now saved to the preferences
file, just like *--pref*. The *--verbose* options still only
apply to the current run.
Take into account --curdir for all relative paths In a lot of places, (potentially) relative paths were passed to File without any processing, making them be resolved without taking into account --curdir. By passing them through Base.absoluteFile instead, these paths are resolved relative to the working directory before starting arduino (at least on Linux, which is currently the only platform supporting --curdir). This applies --curdir to the --preferences-file option and the build.path, settings.path, sketchbook.path preferences. For example, this now works as expected: arduino --pref build.path=build_dir --verify Blink.ino
2014-04-09 22:33:53 +02:00
{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.
Add manual page This adds a description of commandline options, files used and some preferences in proper Unix manpage format. It is written in asciidoc, which can easily be converted to both a native troff manpage, or HTML (the latter can be done by github on-demand).
2013-12-09 10:45:24 +01:00
RESOURCES
---------
Web site: <http://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>
Reference in New Issue Copy Permalink