Postby steveh » Sat Feb 16, 2013 10:16 am
Good evening,
I've just written a Library file for Arduino, and the Tutorial I did said I should create a KEYWORDS.TXT for the Library, but doesn't really explain what this file does.
Is it necessary, if so what does it do ?
Also, every time I change the library, is it correct that I have to delete the object file (.cpp.o) ? This seems to go in a different directory each day and I have to look around to find it.
Is there any compiler directives I can use to automatically delete this ?
The function of it use is in the name, KEYWORDS. If you make a library, you need to make a keywords file so the Arduino can recognize what your doing. Every library has one, and without it you may have problems.
Try this, go into the servo library, keywords and take out SERVO, then see if your still able to use that library correctly.
I have a very basic KEYWORDS.TXT file that only contains a couple of the function names and not others, and it does not appear to affect compilation of the program.
KEYWORD1 is generally used for the classes that you define in your library.
KEYWORD2 is used for the public member functions of the class. Basically these are the class' methods.
LITERAL1 is used for any #defines that are relevant for the user of the library.
I am sure there is more ...
If anyone knows where the reference for the content of this file is located, it would be good to share :).
The following quote is taken from my Beginning C for Arduino book, 2nd ed., page 295:
The keywords.txt File
The Arduino IDE lets you add keywords for syntax highlighting if you wish to do so. For the Dates library, the keywords.txt file contains the following lines:
Note that the format used in the keywords.txt file is pretty fussy. That is, in the first line, Dates is immediately followed by a Tab space, then KEYWORD1. This change causes the class name Dates to appear in the color reserved for KEYWORD1 keywords in your source code files. Using the entries shown here, the word Dates, for example, takes on the same color as for, which, else, etc. when it appears in the source code window of the Arduino IDE.
The next two lines cause the functions defined in the Dates library to have coloring as defined by KEYWORD2. As before, a Tab space must separate the function name from the KEYWORD2 constant. When you view your source code, the words IsLeapYear and GetEaster take on the same color at any other class methods you may use. The two function names, for example, will now have the same color as print in Serial.print().
For the keywords.txt file to take effect, you need to close and reopen the Arduino IDE.
The Dates library mentioned in the quote is taken from a sample library that the chapter builds as an example. The next paragraph in the book explains the themes.txt file, which allows you to change the colors associated with the KEYWORD? directives. I have trouble seeing certain colors, so I changed the colors to make syntax highlighting more readable for me.
The ONLY purpose it serves is for the IDE to be able to recognize keywords and turn them orange in the editor window. That's it. And the messed up thing is that it will turn any keyword from any keywords.txt file in any library orange regardless of whether or not it is included in the sketch. So with too many of those around you start ending up with a bunch of orange on the screen that doesn't mean anything in the context of the program you're working on.
Many of the standard libraries come with it, but most contributed libraries do not. There is absolutely no consequence to leaving it out. The only difference is that you can't make text in the editor window turn orange. But it has no effect on the performance of the IDE or your program.
@Delta_G: true, it does "colorize" the matching keywords in the file. However, I disagree that it doesn't mean anything. If nothing else, you can use it for its designed purpose: To highlight keywords and class methods if you wish to do so. As I said, I have trouble seeing certain colors and the default color (i.e., orange) is one of them, so I changed it to a different color in the themes.txt file which helps me quite a bit when reading source code files.
I agree there is no performance consequence of leaving it out, but of the 71 libraries that I have in my libraries directory, almost 75% (53) do use the keyword.txt file. The individuals who wrote those libraries evidently thought it worthwhile to add the keyword.txt file for whatever reason. If colorizing bothers anyone else, you can go into the themes.txt file and change the KEYWORD? colors to black, which would have the effect of removing the colorizing.
Here's something I just discovered by accident. Can't find any documentation on this action.
There only seem to be 3 variations, a strong and dim orange and dim green/blue. LITERAL2 does not seem to exist, giving dim orange. Here's how to get the 3 variations.
#This makes a strong Orange -- 1 Tab and KEYWORD1
OneTabKW1 KEYWORD1
#This makes a dim Orange -- 2 Tabs and KEYWORD1
TwoTabKW1 KEYWORD1
This makes dim Blue/Green -- 1 Tab and LITERAL1
OneTabLT1 LITERAL1
Same as TwoTabKW1, dim Orange -- 2 Tabs and LITERAL1