Skip to content

Commit d72ca55

Browse files
mcsprmcspr
committed
update doc
1 parent fe3102f commit d72ca55

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
@@ -23,9 +23,9 @@ Actions taken in processing comment block to create ``build.opt``
2323
- for each line, white space is trimmed
2424
- blank lines are skipped
2525
- lines starting with ``*``, ``//``, or ``#`` are skipped
26-
- the remaining results are written to build tree\ ``/core/build.opt``
27-
- multiple ``/*@create-file:build.opt@`` ``*/`` comment blocks are not
28-
allowed
26+
- the remaining results are written to arduino-cli build cache directory
27+
- multiple ``/*@create-file:build.opt@`` ``*/`` comment blocks are
28+
allowed and would be merged in order they are written in the file
2929
- ``build.opt`` is finished with a ``-include ...`` command, which
3030
references the global .h its contents were extracted from.
3131

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

302-
::
171+
.. code-block:: ini
303172
304173
recipe.hooks.prebuild.2.pattern=
305174
build.opt.flags=
306175
176+
307177
Other build confusion
308178
=====================
309179

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

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