Go Down

Topic: Platform.txt custom include folders (Read 3549 times) previous topic - next topic

boylesg

Aug 21, 2017, 08:00 am Last Edit: Aug 21, 2017, 08:00 am by boylesg
Is it possible to specify custom include folders (apart from "C:\Users\greg\Documents\Arduino\libraries" etc) the in platform.txt?

If so what would be the correct syntax for this file?

Code: [Select]

# ctags
# ------------------------------
tools.ctags.path={runtime.tools.ctags.path}
tools.ctags.cmd.path={path}/ctags
tools.ctags.pattern="{cmd.path}" -u --language-force=c++ -f - --c++-kinds=svpf --fields=KSTtzns --line-directives "{source_file}"

# additional entries
tools.avrdude.path={runtime.tools.avrdude.path}

preproc.macros.flags=-w -x c++ -E -CC
#preproc.macros.compatibility_flags={build.mbed_api_include} {build.nRF51822_api_include} {build.ble_api_include} {compiler.libsam.c.flags} {compiler.arm.cmsis.path} {build.variant_system_include}
#recipe.preproc.macros="{compiler.path}{compiler.cpp.cmd}" {compiler.cpreprocessor.flags} {compiler.cpp.flags} {preproc.macros.flags} -DF_CPU={build.f_cpu} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} {compiler.cpp.extra_flags} {build.extra_flags} {preproc.macros.compatibility_flags} {includes} "{source_file}" -o "{preprocessed_file_path}"

pert


boylesg

I already tried to answer this in your other thread where you asked:
http://forum.arduino.cc/index.php?topic=495763.msg3382719#msg3382719
Still unclear how to do it.

If it was a simple gcc command line, that you would use at a unix prompt, then I could immediately understand how to apply a -L flag.

But this platform.txt does not contain simple command line flags.

Where in the file do I setup a -L flag?

And how do I do it?

With a separate line of text "-Lc:\.....\.....\custom include folder"?

Or is there more to it than that?

I need an example basically.

pert

It's really pretty simple. platform.txt defines some properties such as build.extra_flags and then later uses that property in the recipes as {build.extra_flags}. The Arduino IDE uses the recipes during the compilation. So things are a bit spread out through the file but you just have to search for whatever property name you're interested in to see where it's defined and where used.

There are some properties such as runtime.platform.path that are automatically defined by the IDE. You can find documentation for those here:
https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5-3rd-party-Hardware-specification

Just jump in and start learning via trial and error:
  • Edit platform.txt
  • Save platform.txt
  • Restart the Arduino IDE. Changes to platform.txt will only take effect after the restart.
  • Tools > Preferences > Show verbose output during > compilation (check) > OK
  • Compile a sketch
  • Examine the commands that were run during the compilation to verify that your changes to platform.txt had the desired effect. If not then repeat until you get it right.

boylesg

#4
Aug 21, 2017, 05:22 pm Last Edit: Aug 21, 2017, 05:48 pm by boylesg
compiler.c.extra_flags=
compiler.c.elf.extra_flags=
compiler.S.extra_flags=
compiler.cpp.extra_flags=
compiler.ar.extra_flags=
compiler.objcopy.eep.extra_flags=
compiler.elf2hex.extra_flags=

I am a brand new to platform.txt - the first time ever I have even looked at this file and tried to understand it.

What do these mean? What is the correct syntax for the values you apply to them?

Do I put my -L flag on "compiler.c.extra_flags"?
On compiler.c.elf.extra_flags?
On compiler.cpp.extra_flags?
On all of them?
What is .S?
What is .ar?

What is the difference between "elf.extra_flags" and "extra_flags"?
What about includes directives in header files (.h)?

What is the correct syntax?
-L "......"?
-L"......."?
-L{.......}?
L "......"?
L"....."?

None of this file looks like standard looking unix gcc command line stuff - it all looks rather Arduino IDE specific to me.

An example
-c -g -Os {compiler.warning_flags} -std=gnu11 -ffunction-sections -fdata-sections -MMD -flto -fno-fat-lto-objects



And "compiler.c.extra_flags" does not even appear in Arduino-IDE-1.5-3rd-party-Hardware-specification

The above specification is probably adequate if you are one of the Arduino IDE developers and have a fairly sound knowledge of how the compilation process happens.

But as a brand new user of platform.txt, a bit more specific info would be greatly appreciated.

All it would take would be a specific example showing how to use -L and with which these "extra_flags".

boylesg

In fact if some one can supply me with some explanations for

compiler.c.extra_flags=
compiler.c.elf.extra_flags=
compiler.S.extra_flags=
compiler.cpp.extra_flags=
compiler.ar.extra_flags=
compiler.objcopy.eep.extra_flags=
compiler.elf2hex.extra_flags=

Then I would be happy to modify https://github.com/espressif/arduino-esp32/blob/master/platform.txt#L51 with some explanatory comments and examples for these flags (via a pull request) for the benefit any other Arduino IDE users that end asking the same question as me.

pert

In fact if some one can supply me with some explanations for

compiler.c.extra_flags=
compiler.c.elf.extra_flags=
compiler.S.extra_flags=
compiler.cpp.extra_flags=
compiler.ar.extra_flags=
compiler.objcopy.eep.extra_flags=
compiler.elf2hex.extra_flags=
This allows you to add extra flags to the compiler calls. Let's take compiler.cpp.extra_flags as an example. If you do a search of platform.txt for compiler.cpp.extra_flags you will find the definition above and also in recipe.cpp.o.pattern. So what happens is that {compiler.cpp.extra_flags} in the recipe is replaced by whatever you put after the equals sign in the definition at line 57. Super simple right? OK, now it gets a little more complicated. If you read the comment:
Quote
These can be overridden in platform.local.txt
so actually the intended usage for those properties is to allow someone like you to add extra flags without needing to modify platform.txt. So if you create a file named platform.local.txt in the same folder as platform.txt and add the line:
Code: [Select]
compiler.cpp.extra_flags="-Lfoo/bar"
then {compiler.cpp.extra_flags} in recipe.cpp.o.pattern will be replaced with "-Lfoo/bar". The purpose of the empty definitions in platform.txt is actually just to ensure that those properties are always defined. Those definitions in platform.txt are not really intended to be modified but of course you can do so if you like, it just means that every time you update to a new version of the ESP32 core you will need to remember what modifications you made to platform.txt and port those over to the new platform.txt. It's much more simple to just copy your platform.local.txt over and never touch platform.txt so you don't risk accidentally messing it up. There is also the possibility of overriding some of these properties from boards.txt so that you can have flags specific to a certain board selection or custom Tools menu selections.

What do these mean?
Exactly what they say. They are properties that allow you to add extra flags to the recipes.

Do I put my -L flag on "compiler.c.extra_flags"?
On compiler.c.elf.extra_flags?
On compiler.cpp.extra_flags?
It all depends on which recipe you want the flags added to. This would all be completely obvious if you just took a few seconds to to a search through platform.txt for the property names. If you add it to the compiler.c.extra_flags then it will be used in recipe.c.o.pattern and recipe.S.o.pattern (however the latter is due to a typo and I have submitted a PR to fix this. If you add it to compiler.c.elf.extra_flags then it will be used in recipe.c.combine.pattern.

On all of them?
That's generally the purpose of build.extra_flags but of course you can do a search of the file to see which recipes that property is used in.

What is .S?
assembly language

What is .ar?
archive

What is the difference between "elf.extra_flags" and "extra_flags"?
Do a search of platform.txt for any property name and it will be clear.

What is the correct syntax?
-L "......"?
-L"......."?
-L{.......}?
L "......"?
L"....."?
"-L.....". The quotes are only necessary for paths that have a space in them but it's a good habit to get into regardless.

None of this file looks like standard looking unix gcc command line stuff - it all looks rather Arduino IDE specific to me.

An example
-c -g -Os {compiler.warning_flags} -std=gnu11 -ffunction-sections -fdata-sections -MMD -flto -fno-fat-lto-objects
Other than {compiler.warning_flags}, those are just the standard, well documented flags. {compiler.warning_flags} is a little bit tricky because this property can be configured via File > Preferences > Compiler warnings. The options are defined starting at line 16:
Code: [Select]
compiler.warning_flags=-w
compiler.warning_flags.none=-w
compiler.warning_flags.default=
compiler.warning_flags.more=-Wall -Werror=all
compiler.warning_flags.all=-Wall -Werror=all -Wextra

So if you set File > Preferences > Compiler warnings to None then {compiler.warning_flags} is replaced by -w. if you set File > Preferences > Compiler warnings to All then {compiler.warning_flags} is replaced by -Wall -Werror=all -Wextra.


And "compiler.c.extra_flags" does not even appear in Arduino-IDE-1.5-3rd-party-Hardware-specification
Yes, as I already mentioned, that stuff needs to be documented. Unfortunately the author of the code didn't take the time to do so and it's much more difficult for anyone else to do so via deciphering the source code or trial and error reverse engineering how it works.

boylesg

What about header (.h) files?

If I include a file from one of my custom include folders then how is that going to work?

There is no compiler.h.extra_flags=

What if my project contains .c files and I have only filled in -L flag for compiler.cpp.extra_flags=

pert

What about header (.h) files?

If I include a file from one of my custom include folders then how is that going to work?

There is no compiler.h.extra_flags=
I believe the way it works is if you have included the .h file from a .cpp file or an .ino file (which is renamed .cpp before compilation) then the .h file is treated as C++. If you include the .h file from a .c file then it is treated as C.

What if my project contains .c files and I have only filled in -L flag for compiler.cpp.extra_flags=
The flag will not be used when compiling those files.

It's great to learn about how platform.txt works, but are you sure you really need to add custom include folders? I don't really understand how that would be useful.

boylesg

#9
Aug 22, 2017, 01:12 pm Last Edit: Aug 22, 2017, 01:16 pm by boylesg
I believe the way it works is if you have included the .h file from a .cpp file or an .ino file (which is renamed .cpp before compilation) then the .h file is treated as C++. If you include the .h file from a .c file then it is treated as C.
The flag will not be used when compiling those files.

It's great to learn about how platform.txt works, but are you sure you really need to add custom include folders? I don't really understand how that would be useful.
This is the situation I have and where custom include folder would be useful to me.

I have a bunch of classes along the lines of CString, CDate, CTime, CPowerControl,.......

All of them are in their own cpp/h files.

From a maintenance convenience point of view I would rather have these common files located in a folder 'near' my project folder rather than buried in the windows folder hierarchy.

And not have to do this sort of thing #include "..\common\DateTime.h"

And this regime would work well with github.

Where is paltform.local.txt supposed to be located?

PaulS

Quote
Or I create a bunch of individual libraries for each class/cpp/h and then include those libraries in particular projects as needed. But that is also inconvenient from a maintenance point of view.
Why? If "maintenance" of an app means adding new functionality, adding a new header file is part of the job.

boylesg

Why? If "maintenance" of an app means adding new functionality, adding a new header file is part of the job.
Well it is my preference not to have all my common files, that I am still tweaking fairly regularly, buried in an Arduino library and in the windows folder heirarchy.

And, as I said, this will work better with github as well.

pert

Where is paltform.local.txt supposed to be located?
I already told you. I realize this is a lot of information and complex but I'm making the effort to try to answer your questions, the least you can do is actually read what I wrote:
create a file named platform.local.txt in the same folder as platform.txt

Go Up