source: dev-embedded/arduino-bin/files/arduino.1 @ f3987e6

Revision f3987e6, 14.9 KB checked in by Mario Fetka <mario.fetka@…>, 10 months ago (diff)

Bump

  • Property mode set to 100644
Line 
1'\" t
2.\"     Title: arduino
3.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
4.\" Generator: DocBook XSL Stylesheets v1.78.0 <http://docbook.sf.net/>
5.\"      Date: 10/18/2015
6.\"    Manual: \ \&
7.\"    Source: \ \&
8.\"  Language: English
9.\"
10.TH "ARDUINO" "1" "10/18/2015" "\ \&" "\ \&"
11.\" -----------------------------------------------------------------
12.\" * Define some portability stuff
13.\" -----------------------------------------------------------------
14.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15.\" http://bugs.debian.org/507673
16.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18.ie \n(.g .ds Aq \(aq
19.el       .ds Aq '
20.\" -----------------------------------------------------------------
21.\" * set default formatting
22.\" -----------------------------------------------------------------
23.\" disable hyphenation
24.nh
25.\" disable justification (adjust text to left margin only)
26.ad l
27.\" -----------------------------------------------------------------
28.\" * MAIN CONTENT STARTS HERE *
29.\" -----------------------------------------------------------------
30.SH "NAME"
31arduino \- Integrated development environment for Arduino boards
32.SH "SYNOPSIS"
33.sp
34\fBarduino\fR [\fIFILE\&.ino\fR\&...]
35.sp
36\fBarduino\fR [\fB\-\-verify\fR|\fB\-\-upload\fR] [\fB\-\-board\fR \fIpackage\fR:\fIarch\fR:\fIboard\fR[:\fIparameters\fR]] [\fB\-\-port\fR \fIportname\fR] [\fB\-\-pref\fR \fIname\fR=\fIvalue\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-\-preserve\-temp\-files\fR] [\fIFILE\&.ino\fR]
37.sp
38\fBarduino\fR [\fB\-\-get\-pref\fR [\fIpreference\fR]]
39.sp
40\fBarduino\fR [\fB\-\-install\-boards\fR \fIpackage name\fR:\fIplatform architecture\fR[:\fIversion\fR]]
41.sp
42\fBarduino\fR [\fB\-\-install\-library\fR \fIlibrary name\fR[:\fIversion\fR][,\fIlibrary name\fR[:\fIversion\fR],\fIlibrary name\fR[:\fIversion\fR]]
43.SH "DESCRIPTION"
44.sp
45The \fIarduino\fR integrated development environment allows editing, compiling and uploading sketches (programs) for Arduino (and compatible) microcontroller boards\&.
46.sp
47Normally, running the arduino command starts the IDE, optionally loading any \&.ino files specified on the commandline\&.
48.sp
49Alternatively, 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\&.
50.sp
51When running in a one\-off mode, it might be useful to set the \fBbuild\&.path\fR preference to allow keeping intermediate build results between multiple runs and only recompile the files that changed\&.
52.sp
53Note that on MacOS X, the main executable is \fIArduino\&.app/Contents/MacOS/Arduino\fR instead of \fIarduino\fR\&.
54.sp
55Note that on Windows, due to the diffence between GUI and console apps, that the \fIarduino_debug\&.exe\fR is the appropriate executable to use if you want to use the majority of these command line options\&. The \fIarduino\&.exe\fR GUI version of the launcher \fBmay\fR 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\&.
56.sp
57ACTIONS
58.PP
59\fB\-\-verify\fR
60.RS 4
61Build the sketch\&.
62.RE
63.PP
64\fB\-\-upload\fR
65.RS 4
66Build and upload the sketch\&.
67.RE
68.PP
69\fB\-\-get\-pref\fR [\fIpreference\fR]
70.RS 4
71Prints 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\&.
72.RE
73.PP
74\fB\-\-install\-boards\fR \fIpackage name\fR:\fIplatform architecture\fR[:\fIversion\fR]
75.RS 4
76Fetches available board support (platform) list and install the specified one, along with its related tools\&. If
77\fIversion\fR
78is 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\(cqs replaced\&.
79.RE
80.PP
81\fB\-\-install\-library\fR \fIlibrary name\fR[:\fIversion\fR]
82.RS 4
83Fetches available libraries list and install the specified one\&. If
84\fIversion\fR
85is 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\(cqs replaced\&. Multiple libraries can be specified, separated by a comma\&.
86.RE
87.SH "OPTIONS"
88.PP
89\fB\-\-board\fR \fIpackage\fR:\fIarch\fR:\fIboard\fR[:\fIparameters\fR]
90.RS 4
91Select the board to compile for\&.
92.sp
93.RS 4
94.ie n \{\
95\h'-04'\(bu\h'+03'\c
96.\}
97.el \{\
98.sp -1
99.IP \(bu 2.3
100.\}
101
102\fIpackage\fR
103is the identifier of the vendor (the first level folders inside the
104\fIhardware\fR
105directory)\&. Default arduino boards use
106\fIarduino\fR\&.
107.RE
108.sp
109.RS 4
110.ie n \{\
111\h'-04'\(bu\h'+03'\c
112.\}
113.el \{\
114.sp -1
115.IP \(bu 2.3
116.\}
117
118\fIarchitecture\fR
119is the architecture of the board (second level folders inside the
120\fIhardware\fR
121directory)\&. Default arduino boards use either
122\fBarduino:avr\fR
123for all AVR\-based boards (like Uno, Mega or Leonardo) or
124\fBarduino:sam\fR
125for 32bit SAM\-based boards (like Arduino Due)\&.
126.RE
127.sp
128.RS 4
129.ie n \{\
130\h'-04'\(bu\h'+03'\c
131.\}
132.el \{\
133.sp -1
134.IP \(bu 2.3
135.\}
136
137\fIboard\fR
138is the actual board to use, as defined in
139\fIboards\&.txt\fR
140contained in the architecture folder selected\&. For example,
141\fBarduino:avr:uno\fR
142for the Arduino Uno,
143\fBarduino:avr:diecimila\fR
144for the Arduino Duemilanove or Diecimila, or
145\fBarduino:avr:mega\fR
146for the Arduino Mega\&.
147.RE
148.sp
149.RS 4
150.ie n \{\
151\h'-04'\(bu\h'+03'\c
152.\}
153.el \{\
154.sp -1
155.IP \(bu 2.3
156.\}
157
158\fIparameters\fR
159is a comma\-separated list of boards specific parameters that are normally shown under submenus of the "Tools" menu\&. For example
160\fBarduino:avr:nano:cpu=atmega168\fR
161to Select the mega168 variant of the Arduino Nano board\&.
162.RE
163.RE
164.PP
165.RS 4
166If this option is not passed, the value from the current preferences is used (e\&.g\&., the last board selected in the IDE)\&.
167.RE
168.PP
169\fB\-\-port\fR \fIportname\fR
170.RS 4
171Select 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\&.,
172\fB/dev/ttyACM0\fR)\&. On Windows, this should be the name of the serial port (e\&.g\&.,
173\fBCOM3\fR)\&.
174.RE
175.PP
176.RS 4
177If this option is not passed, the value from the current preferences is used (e\&.g\&., the last port selected in the IDE)\&.
178.RE
179.PP
180\fB\-\-verbose\-build\fR
181.RS 4
182Enable verbose mode during build\&. If this option is not given, verbose mode during build is
183\fBdisabled\fR
184regardless of the current preferences\&.
185.RE
186.PP
187\fB\-\-preserve\-temp\-files\fR
188.RS 4
189Keep temporary files (preprocessed sketch, object files\&...) after termination\&. If omitted, temporary files are deleted\&.
190.RE
191.PP
192.RS 4
193This option is only valid together with
194\fB\-\-verify\fR
195or
196\fB\-\-upload\fR\&.
197.RE
198.PP
199\fB\-\-verbose\-upload\fR
200.RS 4
201Enable verbose mode during upload\&. If this option is not given, verbose mode during upload is
202\fBdisabled\fR
203regardless of the current preferences\&.
204.RE
205.PP
206.RS 4
207This option is only valid together with
208\fB\-\-verify\fR
209or
210\fB\-\-upload\fR\&.
211.RE
212.PP
213\fB\-v, \-\-verbose\fR
214.RS 4
215Enable verbose mode during build and upload\&. This option has the same effect of using both
216\fB\-\-verbose\-build\fR
217and
218\fB\-\-verbose\-upload\fR\&.
219.RE
220.PP
221.RS 4
222This option is only valid together with
223\fB\-\-verify\fR
224or
225\fB\-\-upload\fR\&.
226.RE
227.PP
228\fB\-\-preferences\-file\fR \fIfilename\fR
229.RS 4
230Read and store preferences from the specified
231\fIfilename\fR
232instead of the default one\&.
233.RE
234.PP
235\fB\-\-pref\fR \fIname\fR=\fIvalue\fR
236.RS 4
237Sets the preference
238\fIname\fR
239to the given
240\fIvalue\fR\&.
241.RE
242.PP
243.RS 4
244Note 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\&.
245.RE
246.PP
247\fB\-\-save\-prefs\fR
248.RS 4
249Save any (changed) preferences to
250\fBpreferences\&.txt\fR\&. In particular
251\fB\-\-board\fR,
252\fB\-\-port\fR,
253\fB\-\-pref\fR,
254\fB\-\-verbose\fR,
255\fB\-\-verbose\-build\fR
256and
257\fB\-\-verbose\-upload\fR
258may alter the current preferences\&.
259.RE
260.SH "PREFERENCES"
261.sp
262Arduino keeps a list of preferences, as simple name and value pairs\&. Below, a few of them are documented but a lot more are available\&.
263.PP
264\fBsketchbook\&.path\fR
265.RS 4
266The path where sketches are (usually) stored\&. This path can also contain some special subdirectories (see FILES below)\&.
267.RE
268.PP
269\fBupdate\&.check\fR
270.RS 4
271When set to true, the IDE checks for a new version on startup\&.
272.RE
273.PP
274\fBeditor\&.external\fR
275.RS 4
276When set to true, use an external editor (the IDE does not allow editing and reloads each file before verifying)\&.
277.RE
278.PP
279\fBbuild\&.path\fR
280.RS 4
281The path to use for building\&. This is where things like the preprocessed \&.cpp file, compiled \&.o files and the final \&.hex file go\&.
282.RE
283.PP
284.RS 4
285If set, this directory should already exist before running the arduino command\&.
286.RE
287.PP
288.RS 4
289If 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\&.
290.RE
291.SH "EXIT STATUS"
292.PP
293\fB0\fR
294.RS 4
295Success
296.RE
297.PP
298\fB1\fR
299.RS 4
300Build failed or upload failed
301.RE
302.PP
303\fB2\fR
304.RS 4
305Sketch not found
306.RE
307.PP
308\fB3\fR
309.RS 4
310Invalid (argument for) commandline option
311.RE
312.PP
313\fB4\fR
314.RS 4
315Preference passed to
316\fB\-\-get\-pref\fR
317does not exist
318.RE
319.SH "FILES"
320.PP
321\fB~/\&.arduino15/preferences\&.txt\fR
322.RS 4
323This file stores the preferences used for the IDE, building and uploading sketches\&.
324.RE
325.PP
326\fBMy Documents/Arduino/\fR (Windows), \fB~/Documents/Arduino/\fR (Mac OS X), \fB~/Arduino/\fR (Linux)
327.RS 4
328This directory is referred to as the "Sketchbook" and contains the user\(cqs sketches\&. The path can be changed through the
329\fBsketchbook\&.path\fR
330preference\&.
331.RE
332.PP
333.RS 4
334Apart from sketches, three special directories can be inside the sketchbook:
335.PP
336\fBlibraries\fR
337.RS 4
338Libraries can be put inside this directory, one library per subdirectory\&.
339.RE
340.PP
341\fBhardware\fR
342.RS 4
343Support for third\-party hardware can be added through this directory\&.
344.RE
345.PP
346\fBtools\fR
347.RS 4
348External code\-processing tools (that can be run through the Tools menu of the IDE) can be added here\&.
349.RE
350.RE
351.SH "EXAMPLES"
352.sp
353Start the Arduino IDE, with two files open:
354.sp
355.if n \{\
356.RS 4
357.\}
358.nf
359arduino /path/to/sketch/sketch\&.ino /path/to/sketch/extra\&.ino
360.fi
361.if n \{\
362.RE
363.\}
364.sp
365Compile and upload a sketch using the last selected board and serial port
366.sp
367.if n \{\
368.RS 4
369.\}
370.nf
371arduino \-\-upload /path/to/sketch/sketch\&.ino
372.fi
373.if n \{\
374.RE
375.\}
376.sp
377Compile and upload a sketch to an Arduino Nano, with an Atmega168 CPU, connected on port \fI/dev/ttyACM0\fR:
378.sp
379.if n \{\
380.RS 4
381.\}
382.nf
383arduino \-\-board arduino:avr:nano:cpu=atmega168 \-\-port /dev/ttyACM0 \-\-upload /path/to/sketch/sketch\&.ino
384.fi
385.if n \{\
386.RE
387.\}
388.sp
389Compile a sketch, put the build results in the \fIbuild\fR directory an re\-use any previous build results in that directory\&.
390.sp
391.if n \{\
392.RS 4
393.\}
394.nf
395arduino \-\-pref build\&.path=/path/to/sketch/build \-\-verify /path/to/sketch/sketch\&.ino
396.fi
397.if n \{\
398.RE
399.\}
400.sp
401Change the selected board and build path and do nothing else\&.
402.sp
403.if n \{\
404.RS 4
405.\}
406.nf
407arduino \-\-pref build\&.path=/path/to/sketch/build \-\-board arduino:avr:uno \-\-save\-prefs
408.fi
409.if n \{\
410.RE
411.\}
412.sp
413Install latest SAM board support
414.sp
415.if n \{\
416.RS 4
417.\}
418.nf
419arduino \-\-install\-boards "arduino:sam"
420.fi
421.if n \{\
422.RE
423.\}
424.sp
425Install AVR board support, 1\&.6\&.2
426.sp
427.if n \{\
428.RS 4
429.\}
430.nf
431arduino \-\-install\-boards "arduino:avr:1\&.6\&.2"
432.fi
433.if n \{\
434.RE
435.\}
436.sp
437Install Bridge library version 1\&.0\&.0
438.sp
439.if n \{\
440.RS 4
441.\}
442.nf
443arduino \-\-install\-library "Bridge:1\&.0\&.0"
444.fi
445.if n \{\
446.RE
447.\}
448.sp
449Install Bridge and Servo libraries
450.sp
451.if n \{\
452.RS 4
453.\}
454.nf
455arduino \-\-install\-library "Bridge:1\&.0\&.0,Servo:1\&.2\&.0"
456.fi
457.if n \{\
458.RE
459.\}
460.SH "BUGS"
461.sp
462Even in command line mode the Arduino IDE requires a graphical user interface to be present\&. This should usually be the case in Windows or Mac OS X\&. On Linux however you might want to compile and upload sketches when logged in via SSH or in batch mode\&. To accomplish this, install the Xvfb dummy X server and write a small wrapper script to create an instance of this Xserver, run the Arduino IDE in it and kill the Xserver afterwards:
463.sp
464.if n \{\
465.RS 4
466.\}
467.nf
468#!/bin/bash
469Xvfb :1 \-nolisten tcp \-screen :1 1280x800x24 &
470xvfb="$!"
471DISPLAY=:1 arduino $@
472kill \-9 $xvfb
473.fi
474.if n \{\
475.RE
476.\}
477.sp
478Save the script as \fBarduino\-headless\fR and run it with the options described above\&. If the script does not return to a shell prompt, the options you specified were wrong and the Arduino IDE actually opened a window, stop its execution with Ctrl+C\&.
479.SH "HISTORY"
480.PP
4811\&.5\&.2
482.RS 4
483Added initial commandline support\&. This introduced
484\fB\-\-verify\fR,
485\fB\-\-upload\fR,
486\fB\-\-board\fR,
487\fB\-\-port\fR,
488\fB\-\-verbose\fR
489and
490\fB\-v\fR\&.
491.RE
492.PP
4931\&.5\&.5
494.RS 4
495Added support for board\-specific parameters to
496\fB\-\-board\fR\&.
497.RE
498.PP
499.RS 4
500Sketch filenames are now interpreted relative to the current directory instead of the location of the arduino command itself\&.
501.RE
502.PP
5031\&.5\&.6
504.RS 4
505Introduced
506\fB\-\-pref\fR,
507\fB\-\-preferences\-file\fR,
508\fB\-\-verbose\-build\fR
509and
510\fB\-\-verbose\-upload\fR\&.
511.RE
512.PP
513.RS 4
514Preferences set through \-\-pref are remembered, preferences set through
515\fB\-\-board\fR,
516\fB\-\-port\fR
517or the
518\fB\-\-verbose\fR
519options are not\&.
520.RE
521.PP
522.RS 4
523When running with
524\fB\-\-verify\fR
525or
526\fB\-\-upload\fR, the full GUI is no longer shown\&. Error messages still use a graphical popup and on Windows, the splash screen is still shown\&.
527.RE
528.PP
5291\&.5\&.8
530.RS 4
531Introduced
532\fB\-\-save\-prefs\fR\&.
533.RE
534.PP
5351\&.6\&.2
536.RS 4
537Main executable in MacOS X changed from
538\fIArduino\&.app/Contents/MacOS/JavaApplicationStub\fR
539to
540\fIArduino\&.app/Contents/MacOS/Arduino\fR\&.
541.RE
542.PP
5431\&.6\&.4
544.RS 4
545Introduced
546\fB\-\-install\-boards\fR
547and
548\fB\-\-install\-library\fR\&.
549.RE
550.PP
551.RS 4
552
553\fB\-\-pref\fR
554options are now not saved to the preferences file, just like
555\fB\-\-board\fR
556and
557\fB\-\-port\fR, unless
558\fB\-\-save\-prefs\fR
559is specified\&.
560.RE
561.PP
562.RS 4
563A path passed to
564\fB\-\-preferences\-file\fR, or set in the
565\fBbuild\&.path\fR,
566\fBpreferences\&.path\fR
567or
568\fBsettings\&.path\fR
569is now interpreted relative to the current directory instead of the location of the arduino command itself\&.
570.RE
571.SH "RESOURCES"
572.sp
573Web site: http://www\&.arduino\&.cc/
574.sp
575Help on projects and programming: http://forum\&.arduino\&.cc/
576.sp
577Report bugs: http://github\&.com/arduino/Arduino/issues
578.sp
579IDE and framework development mailing list: https://groups\&.google\&.com/a/arduino\&.cc/forum/#!forum/developers
Note: See TracBrowser for help on using the repository browser.