Skip to content

Commit 47b2d77

Browse files
mcsprmcspr
committed
update doc
1 parent 7290d27 commit 47b2d77

File tree

2 files changed

+158
-144
lines changed

2 files changed

+158
-144
lines changed

‎doc/faq/a06-global-build-options.rst

Lines changed: 8 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@ Actions taken in processing comment block to create ``build.opt``
2525
- for each line, white space is trimmed
2626
- blank lines are skipped
2727
- lines starting with ``*``, ``//``, or ``#`` are skipped
28-
- the remaining results are written to build tree\ ``/core/build.opt``
29-
- multiple ``/*@create-file:build.opt@`` ``*/`` comment blocks are not
30-
allowed
28+
- the remaining results are written to arduino-cli build cache directory
29+
- multiple ``/*@create-file:build.opt@`` ``*/`` comment blocks are
30+
allowed and would be merged in order they are written in the file
3131
- ``build.opt`` is finished with a ``-include ...`` command, which
3232
references the global .h its contents were extracted from.
3333

@@ -160,137 +160,6 @@ Updated Global ``.h`` file: ``LowWatermark.ino.globals.h``
160160
161161
#endif
162162
163-
Aggressively cache compiled core
164-
================================
165-
166-
This feature appeared with the release of Arduino IDE 1.8.2. The feature
167-
“Aggressively Cache Compiled core” refers to sharing a single copy of
168-
``core.a`` across all Arduino IDE Sketch windows. This feature is on by
169-
default. ``core.a`` is an archive file containing the compiled objects
170-
of ``./core/esp8266/*``. Created after your 1ST successful compilation.
171-
All other open sketch builds use this shared file. When you close all
172-
Arduino IDE windows, the core archive file is deleted.
173-
174-
This feature is not compatible with using global defines or compiler
175-
command-line options. Without mediation, bad builds could result, when
176-
left enabled. When ``#define`` changes require rebuilding ``core.a`` and
177-
multiple Sketches are open, they can no longer reliably share one cached
178-
``core.a``. In a simple case: The 1st Sketch to be built has its version
179-
of ``core.a`` cached. Other sketches will use this cached version for
180-
their builds.
181-
182-
There are two solutions to this issue:
183-
184-
1. Do nothing, and rely on aggressive cache workaround built into the
185-
script.
186-
2. Turn off the “Aggressively Cache Compiled core” feature, by setting
187-
``compiler.cache_core=false``.
188-
189-
Using “compiler.cache_core=false”
190-
---------------------------------
191-
192-
There are two ways to turn off the “Aggressively Cache Compiled core”
193-
feature: This can be done with the Arduino IDE command-line or a text
194-
editor.
195-
196-
Using the Arduino IDE command-line from a system command line, enter the
197-
following:
198-
199-
::
200-
201-
arduino --pref compiler.cache_core=false --save-prefs
202-
203-
For the text editor, you need to find the location of
204-
``preferences.txt``. From the Arduino IDE, go to *File->Preferences*.
205-
Make note of the path to ``prefereces.txt``. You *cannot* edit the file
206-
while the Arduino IDE is running. Close all Arduino IDE windows and edit
207-
the file ``preferences.txt``. Change ``compiler.cache_core=true`` to
208-
``compiler.cache_core=false`` and save. Then each sketch will maintain
209-
its *own* copy of ``core.a`` built with the customization expressed by
210-
their respective ``build.opt`` file.
211-
212-
The “workaround”
213-
----------------
214-
215-
When the “Aggressively Cache Compiled core” feature is enabled and the
216-
global define file is detected, a workaround will turn on and stay on.
217-
When you switch between Sketch windows, core will be recompiled and the
218-
cache updated. The workaround logic is reset when Arduino IDE is
219-
completely shutdown and restarted.
220-
221-
The workaround is not perfect. These issues may be of concern:
222-
223-
1. Dirty temp space. Arduino build cache files left over from a previous
224-
run or boot.
225-
2. Arduino command-line options:
226-
227-
- override default preferences.txt file.
228-
- override a preference, specifically ``compiler.cache_core``.
229-
230-
3. Multiple versions of the Arduino IDE running
231-
232-
**Dirty temp space**
233-
234-
A minor concern, the workaround is always on. Not an issue for build
235-
accuracy, but ``core.a`` maybe rebuild more often than necessary.
236-
237-
Some operating systems are better at cleaning up their temp space than
238-
others at reboot after a crash. At least for Windows®, you may need to
239-
manually delete the Arduino temp files and directories after a crash.
240-
Otherwise, the workaround logic may be left on. There is no harm in the
241-
workaround being stuck on, the build will be correct; however, the core
242-
files will occasionally be recompiled when not needed.
243-
244-
For some Windows® systems the temp directory can be found near
245-
``C:\Users\<user id>\AppData\Local\Temp\arduino*``. Note ``AppData`` is
246-
a hidden directory. For help with this do an Internet search on
247-
``windows disk cleanup``. Or, type ``disk cleanup`` in the Windows®
248-
taskbar search box.
249-
250-
With Linux, this problem could occur after an Arduino IDE crash. The
251-
problem would be cleared after a reboot. Or you can manually cleanup the
252-
``/tmp/`` directory before restarting the Arduino IDE.
253-
254-
**Arduino command-line option overrides**
255-
256-
If you are building with ``compiler.cache_core=true`` no action is
257-
needed. If ``false`` the script would benefit by knowing that.
258-
259-
When using either of these two command-line options:
260-
261-
::
262-
263-
./arduino --preferences-file other-preferences.txt
264-
./arduino --pref compiler.cache_core=false
265-
266-
Hints for discovering the value of ``compiler.cache_core``, can be
267-
provided by specifying ``mkbuildoptglobals.extra_flags=...`` in
268-
``platform.local.txt``.
269-
270-
Examples of hints:
271-
272-
::
273-
274-
mkbuildoptglobals.extra_flags=--preferences_sketch # assume file preferences.txt in the sketch folder
275-
mkbuildoptglobals.extra_flags=--preferences_sketch "pref.txt" # is relative to the sketch folder
276-
mkbuildoptglobals.extra_flags=--no_cache_core
277-
mkbuildoptglobals.extra_flags=--cache_core
278-
mkbuildoptglobals.extra_flags=--preferences_file "other-preferences.txt" # relative to IDE or full path
279-
280-
If required, remember to quote file or file paths.
281-
282-
**Multiple versions of the Arduino IDE running**
283-
284-
You can run multiple Arduino IDE windows as long as you run one version
285-
of the Arduino IDE at a time. When testing different versions,
286-
completely exit one before starting the next version. For example,
287-
Arduino IDE 1.8.19 and Arduino IDE 2.0 work with different temp and
288-
build paths. With this combination, the workaround logic sometimes fails
289-
to enable.
290-
291-
At the time of this writing, when Arduino IDE 2.0 rc5 exits, it leaves
292-
the temp space dirty. This keeps the workaround active the next time the
293-
IDE is started. If this is an issue, manually delete the temp files.
294163
295164
Custom build environments
296165
=========================
@@ -301,11 +170,12 @@ require this feature and would like to turn it off, you can add the
301170
following lines to the ``platform.local.txt`` used in your build
302171
environment:
303172

304-
::
173+
.. code-block:: ini
305174
306175
recipe.hooks.prebuild.2.pattern=
307176
build.opt.flags=
308177
178+
309179
Other build confusion
310180
=====================
311181

@@ -315,12 +185,6 @@ Other build confusion
315185
name ``LowWatermark.ino.globals.h``. You need to touch (update
316186
timestamp) the file so a “rebuild all” is performed.
317187

318-
2. When a ``.h`` file is renamed in the sketch folder, a copy of the old
319-
file remains in the build sketch folder. This can create confusion if
320-
you missed an edit in updating an ``#include`` in one or more of your
321-
modules. That module will continue to use the stale version of the
322-
``.h`` until you restart the IDE or other major changes that would
323-
cause the IDE to delete and recopy the contents from the source
324-
Sketch directory. Changes on the IDE Tools board settings may cause a
325-
complete rebuild, clearing the problem. This may be the culprit for
326-
“What! It built fine last night!”
188+
2. Original script relied on IDE 1.x core & sketch caching behaviour.
189+
Since 3.2.x, we no longer assume aggressive caching can be disabled.
190+
`Read more <a07-mkbuildoptglobals-aggressive-caching.rst>`__.

‎doc/faq/a07-mkbuildoptglobals-aggressive-caching.rst

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
:orphan:
2+
3+
.. attention::
4+
5+
This article applies ONLY to IDE 1.x and original version
6+
of the mkbuildoptglobals.py script shipped with Core 3.1.x
7+
8+
Aggressively cache compiled core
9+
================================
10+
11+
This feature appeared with the release of Arduino IDE 1.8.2. The feature
12+
“Aggressively Cache Compiled core” refers to sharing a single copy of
13+
``core.a`` across all Arduino IDE Sketch windows. This feature is on by
14+
default. ``core.a`` is an archive file containing the compiled objects
15+
of ``./core/esp8266/*``. Created after your 1ST successful compilation.
16+
All other open sketch builds use this shared file. When you close all
17+
Arduino IDE windows, the core archive file is deleted.
18+
19+
This feature is not compatible with using global defines or compiler
20+
command-line options. Without mediation, bad builds could result, when
21+
left enabled. When ``#define`` changes require rebuilding ``core.a`` and
22+
multiple Sketches are open, they can no longer reliably share one cached
23+
``core.a``. In a simple case: The 1st Sketch to be built has its version
24+
of ``core.a`` cached. Other sketches will use this cached version for
25+
their builds.
26+
27+
There are two solutions to this issue:
28+
29+
1. Do nothing, and rely on aggressive cache workaround built into the
30+
script.
31+
2. Turn off the “Aggressively Cache Compiled core” feature, by setting
32+
``compiler.cache_core=false``.
33+
34+
Using “compiler.cache_core=false”
35+
---------------------------------
36+
37+
There are two ways to turn off the “Aggressively Cache Compiled core”
38+
feature: This can be done with the Arduino IDE command-line or a text
39+
editor.
40+
41+
Using the Arduino IDE command-line from a system command line, enter the
42+
following:
43+
44+
.. code-block:: console
45+
46+
$ arduino --pref compiler.cache_core=false --save-prefs
47+
48+
For the text editor, you need to find the location of
49+
``preferences.txt``. From the Arduino IDE, go to *File->Preferences*.
50+
Make note of the path to ``prefereces.txt``. You *cannot* edit the file
51+
while the Arduino IDE is running. Close all Arduino IDE windows and edit
52+
the file ``preferences.txt``. Change ``compiler.cache_core=true`` to
53+
``compiler.cache_core=false`` and save. Then each sketch will maintain
54+
its *own* copy of ``core.a`` built with the customization expressed by
55+
their respective ``build.opt`` file.
56+
57+
The “workaround”
58+
----------------
59+
60+
When the “Aggressively Cache Compiled core” feature is enabled and the
61+
global define file is detected, a workaround will turn on and stay on.
62+
When you switch between Sketch windows, core will be recompiled and the
63+
cache updated. The workaround logic is reset when Arduino IDE is
64+
completely shutdown and restarted.
65+
66+
The workaround is not perfect. These issues may be of concern:
67+
68+
1. Dirty temp space. Arduino build cache files left over from a previous
69+
run or boot.
70+
2. Arduino command-line options:
71+
72+
- override default preferences.txt file.
73+
- override a preference, specifically ``compiler.cache_core``.
74+
75+
3. Multiple versions of the Arduino IDE running
76+
77+
**Dirty temp space**
78+
79+
A minor concern, the workaround is always on. Not an issue for build
80+
accuracy, but ``core.a`` maybe rebuild more often than necessary.
81+
82+
Some operating systems are better at cleaning up their temp space than
83+
others at reboot after a crash. At least for Windows®, you may need to
84+
manually delete the Arduino temp files and directories after a crash.
85+
Otherwise, the workaround logic may be left on. There is no harm in the
86+
workaround being stuck on, the build will be correct; however, the core
87+
files will occasionally be recompiled when not needed.
88+
89+
For some Windows® systems the temp directory can be found near
90+
``C:\Users\<user id>\AppData\Local\Temp\arduino*``. Note ``AppData`` is
91+
a hidden directory. For help with this do an Internet search on
92+
``windows disk cleanup``. Or, type ``disk cleanup`` in the Windows®
93+
taskbar search box.
94+
95+
With Linux, this problem could occur after an Arduino IDE crash. The
96+
problem would be cleared after a reboot. Or you can manually cleanup the
97+
``/tmp/`` directory before restarting the Arduino IDE.
98+
99+
**Arduino command-line option overrides**
100+
101+
If you are building with ``compiler.cache_core=true`` no action is
102+
needed. If ``false`` the script would benefit by knowing that.
103+
104+
When using either of these two command-line options:
105+
106+
.. code-block:: console
107+
108+
$ arduino --preferences-file other-preferences.txt
109+
$ arduino --pref compiler.cache_core=false
110+
111+
Hints for discovering the value of ``compiler.cache_core``, can be
112+
provided by specifying ``mkbuildoptglobals.extra_flags=...`` in
113+
``platform.local.txt``.
114+
115+
Examples of hints:
116+
117+
.. code-block:: ini
118+
119+
mkbuildoptglobals.extra_flags=--preferences_sketch # assume file preferences.txt in the sketch folder
120+
mkbuildoptglobals.extra_flags=--preferences_sketch "pref.txt" # is relative to the sketch folder
121+
mkbuildoptglobals.extra_flags=--no_cache_core
122+
mkbuildoptglobals.extra_flags=--cache_core
123+
mkbuildoptglobals.extra_flags=--preferences_file "other-preferences.txt" # relative to IDE or full path
124+
125+
If required, remember to quote file or file paths.
126+
127+
Multiple versions of the Arduino IDE running
128+
--------------------------------------------
129+
130+
You can run multiple Arduino IDE windows as long as you run one version
131+
of the Arduino IDE at a time. When testing different versions,
132+
completely exit one before starting the next version. For example,
133+
Arduino IDE 1.8.19 and Arduino IDE 2.0 work with different temp and
134+
build paths. With this combination, the workaround logic sometimes fails
135+
to enable.
136+
137+
At the time of this writing, when Arduino IDE 2.0 rc5 exits, it leaves
138+
the temp space dirty. This keeps the workaround active the next time the
139+
IDE is started. If this is an issue, manually delete the temp files.
140+
141+
Also note when a ``.h`` file is renamed in the sketch folder, a copy of the old
142+
file remains in the build sketch folder. This can create confusion if
143+
you missed an edit in updating an ``#include`` in one or more of your
144+
modules. That module will continue to use the stale version of the
145+
``.h`` until you restart the IDE or other major changes that would
146+
cause the IDE to delete and recopy the contents from the source
147+
Sketch directory. Changes on the IDE Tools board settings may cause a
148+
complete rebuild, clearing the problem. This may be the culprit for
149+
“What! It built fine last night!”
150+

0 commit comments

Comments
 (0)