From aa686413af635786b7e11bfd80a7fa74ea50838b Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Wed, 2 Mar 2022 12:38:30 -0800 Subject: [PATCH 1/5] Make use of 'avr' as example platform more consistent It's fairly easy to miss the one line early in the doc that says this text uses 'avr' as an example, leading a reader to possibly believe the documentation hasn't been updated since 'avr' was the only platform choice. Within the doc, the text was a little inconsistent as to how it referred to the avr platform and platform specific tools. This change tries to standardize how we refer to the example platform. --- docs/sketch-build-process.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md index 25347481a23..ec7669a5bf4 100644 --- a/docs/sketch-build-process.md +++ b/docs/sketch-build-process.md @@ -1,12 +1,12 @@ The process the Arduino development software uses to build a sketch. More useful information can be found in the [Arduino platform specification](platform-specification.md). Note that the following refers specifically to the build -process for AVR targets. Other architectures will have a similar build process. +process for AVR targets. Other architectures follow a similar build process, but may use other tools and compilers. ## Overview A number of things have to happen for your Arduino code to get onto the Arduino board. First, the Arduino development software performs some minor pre-processing to turn your sketch into a C++ program. Next, dependencies of the sketch are -located. It then gets passed to a compiler (avr-gcc), which turns the human readable code into machine readable +located. It then gets passed to a compiler (e.g, `avr-gcc`), which turns the human readable code into machine readable instructions (or object files). Then your code gets combined with (linked against) the standard Arduino libraries that provide basic functions like `digitalWrite()` or `Serial.print()`. The result is a single Intel hex file, which contains the specific bytes that need to be written to the program memory of the chip on the Arduino board. This file is then @@ -15,8 +15,8 @@ external programming hardware. ## Pre-Processing -The Arduino development software performs a few transformations to your sketch before passing it to the avr-gcc -compiler: +The Arduino development software performs a few transformations to your sketch before passing it to the +compiler (e.g., `avr-gcc`): - All .ino and .pde files in the sketch folder (shown in the Arduino IDE as tabs with no extension) are concatenated together, starting with the file that matches the folder name followed by the others in alphabetical order. The .cpp @@ -157,7 +157,7 @@ its cloud-based nature may make the locations of libraries less obvious. ## Compilation -Sketches are compiled by avr-gcc and avr-g++ according to the variables in the boards.txt file of the selected board's +Sketches are compiled by platform-specific versions of `gcc` and `g++` according to the variables in the boards.txt file of the selected board's [platform](platform-specification.md). The sketch is built in a temporary directory in the system-wide temporary directory (e.g. /tmp on Linux). @@ -185,8 +185,8 @@ the build process will be printed in the console. ## Uploading -Sketches are uploaded by avrdude. The upload process is also controlled by variables in the boards and main preferences +Sketches are uploaded by a platform-specific upload tool (e.g., avrdude). The upload process is also controlled by variables in the boards and main preferences files. See the [Arduino platform specification](platform-specification.md) page for details. -If verbose output during upload is enabled, debugging information will be output to the console, including avrdude +If verbose output during upload is enabled, debugging information will be output to the console, including the upload tool's command lines and verbose output. From 2e7340b6fab87528808484110bbb6f5fd1d492dd Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Wed, 2 Mar 2022 12:56:08 -0800 Subject: [PATCH 2/5] Fix a couple lint errors. --- docs/sketch-build-process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md index ec7669a5bf4..d834ccc045b 100644 --- a/docs/sketch-build-process.md +++ b/docs/sketch-build-process.md @@ -15,8 +15,8 @@ external programming hardware. ## Pre-Processing -The Arduino development software performs a few transformations to your sketch before passing it to the -compiler (e.g., `avr-gcc`): +The Arduino development software performs a few transformations to your sketch before passing it to the +compiler (e.g., `avr-gcc`): - All .ino and .pde files in the sketch folder (shown in the Arduino IDE as tabs with no extension) are concatenated together, starting with the file that matches the folder name followed by the others in alphabetical order. The .cpp From d2c7786edc081c4474607a5795c0f2eb307e99f5 Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Wed, 2 Mar 2022 13:03:26 -0800 Subject: [PATCH 3/5] Fix prettier lint errors. --- docs/sketch-build-process.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md index d834ccc045b..7a7f299803f 100644 --- a/docs/sketch-build-process.md +++ b/docs/sketch-build-process.md @@ -157,8 +157,8 @@ its cloud-based nature may make the locations of libraries less obvious. ## Compilation -Sketches are compiled by platform-specific versions of `gcc` and `g++` according to the variables in the boards.txt file of the selected board's -[platform](platform-specification.md). +Sketches are compiled by platform-specific versions of `gcc` and `g++` according to the variables in the boards.txt file +of the selected board's [platform](platform-specification.md). The sketch is built in a temporary directory in the system-wide temporary directory (e.g. /tmp on Linux). @@ -185,8 +185,9 @@ the build process will be printed in the console. ## Uploading -Sketches are uploaded by a platform-specific upload tool (e.g., avrdude). The upload process is also controlled by variables in the boards and main preferences -files. See the [Arduino platform specification](platform-specification.md) page for details. +Sketches are uploaded by a platform-specific upload tool (e.g., avrdude). The upload process is also controlled by +variables in the boards and main preferences files. See the [Arduino platform specification](platform-specification.md) +page for details. -If verbose output during upload is enabled, debugging information will be output to the console, including the upload tool's -command lines and verbose output. +If verbose output during upload is enabled, debugging information will be output to the console, including the upload +tool's command lines and verbose output. From 6636919e4381fc8824b27c6f0cc326456daff9ae Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Wed, 2 Mar 2022 13:07:33 -0800 Subject: [PATCH 4/5] Fix an additional prettier lint error --- docs/sketch-build-process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md index 7a7f299803f..d0b216cca10 100644 --- a/docs/sketch-build-process.md +++ b/docs/sketch-build-process.md @@ -15,8 +15,8 @@ external programming hardware. ## Pre-Processing -The Arduino development software performs a few transformations to your sketch before passing it to the -compiler (e.g., `avr-gcc`): +The Arduino development software performs a few transformations to your sketch before passing it to the compiler (e.g., +`avr-gcc`): - All .ino and .pde files in the sketch folder (shown in the Arduino IDE as tabs with no extension) are concatenated together, starting with the file that matches the folder name followed by the others in alphabetical order. The .cpp From c16d856a1d5ae43b5e4100a8e439df9c38ab46be Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Thu, 3 Mar 2022 21:39:09 -0800 Subject: [PATCH 5/5] Update docs/sketch-build-process.md Co-authored-by: per1234 --- docs/sketch-build-process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md index d0b216cca10..ccf3cecbaef 100644 --- a/docs/sketch-build-process.md +++ b/docs/sketch-build-process.md @@ -157,8 +157,8 @@ its cloud-based nature may make the locations of libraries less obvious. ## Compilation -Sketches are compiled by platform-specific versions of `gcc` and `g++` according to the variables in the boards.txt file -of the selected board's [platform](platform-specification.md). +Sketches are compiled by architecture-specific versions of `gcc` and `g++` according to the variables in the boards.txt +file of the selected board's [platform](platform-specification.md). The sketch is built in a temporary directory in the system-wide temporary directory (e.g. /tmp on Linux).