Say I have huge project and in many source files there is included common header:
#include "some_common.h"
This causes that generated dot 'Include dependency graph' contains many arrows ending in one common header. For documentation purposes I do not need to see this reference. Let's say it is common knowledge in my team.
Is it possible to filter the header includes within doxygen config file? How?
To be more specific I do not want to touch the processed source code.
Related
Erlang's -import() directive lets you import code from other modules. Its include() directive lets you import code from headers. Why reasons are there to prefer either one over the other?
My hunch is that headers are good for short, easy-on-the-compiler kinds of code, such as record definitions, when you don't want to have to qualify the
Learn You Some Erlang states[1] that "Erlang header files are pretty similar to their C counter-part: they're nothing but a snippet of code that gets added to the module as if it were written there in the first place." Thus inclusion seems to cause the compiler to duplicate effort across different modules. And header files are what appear to be an optional complication on top of the mandatory module system. So why would I ever use a header file?
[1] https://learnyousomeerlang.com/a-short-visit-to-common-data-structures
Erlang's -import just allows you to call imported functions without the Module. It hurts legibility and should not be used: You need to check the import directive to know whether a function is local or external to the module.
With header files you get the same functionality as in C, you can use them to share -record definitions instead of having a dto-like module (1), you can use them to include -defines to use the same macros (2).
1:
-record(position, {x, y}).
Imagine that you have #position{} throughout the code, instead of defining the record everywhere and updating all of the copies when the record definition changes, you use a header (or a dto module with opaque types, but that's for another question).
And let's just hope that you remember to update all the copies, otherwise chaos ensues.
2:
-define(ENUM01, enum01).
-define(DEFAULT_TIMEOUT, 1000).
Instead of using enum01 and 1000 everywhere, which is error prone and requires multiple updates if you need to change them, you define them in a header and use them as ?ENUM01 and ?DEFAULT_TIMEOUT
Or you can be more thorough when testing:
-ifdef(TEST).
-define(assert(A), true = A).
-else
-define(assert(A), A).
-endif.
Or you can include some useful information:
-define(LOG(Level, X), logger:log(Level, X, #{line => ?LINE}).
The Erlang standard library uses header files to provide the ability to add metadata to your code.
For instance, EUnit functionality:
-include_lib("eunit/include/eunit.hrl").
import is helpful in building encapsulations, whereas include is kind of pre-processing(which means code will be part of the unit before it gets through the compiler).
An import ensues a dependency between two modules, which means a module A importing module B has B as dependency ... Whereas an include is extensional which means a module has included some code and that code is part of the module itself, and that is what header files do.
module(s) and header(s) are 2 semantically different things and serve different purposes. With modules, we can build abstractions by using the export(s), keep things confined by not exporting them, import from other modules(but they are not exported by default), re-export imported things etc etc. So when we import stuff, we can call upon functions from the other module, but only those which are exported in the other module. However that is not the case with header files. Everything inside a header file becomes part of the module which includes them. There is no sense of export/import inside header files. And header files are quite useful for writing and distributing definition(s) which otherwise could lead to redundancy in case of large programs.
So essentially they are 2 different things, so 2 different keywords available at our disposal. So don't prefer one over the other. Learn both of them as we need both of them.
I'm trying to understand mapping of URIs to files. Let's take this URI:
modelica://foo.bar/file.png
Is it correct that there are two possible locations for file.png?
It could be either
$MODELICAPATH/foo/file.png if file $MODELICAPATH/foo/bar.mo exists.
Or
$MODELICAPATH/foo/bar/file.png if file $MODELICAPATH/foo/bar/package.mo exists.
Likely Section "13.2.3 External resources" of the Modelica Language Specification helps.
A little modification of your example should help to understand how it works. Using modelica://foo/bar/file.png refers to foo as top-level package/library. The library the path is resolved when it is loaded in the simulation environment. In case you store the library hierarchically (i.e. every package is represented as folder, each model is a file) bar would be a subfolder within the libraries root directory. file.png would be the file name within bar.
This is different if the package is stored as a single file, but as this has several disadvantages I would recommend to go with the hierarchical option.
No need to edit $ModelicaPath$ if the library is loaded.
Usually pictures etc. are put into a Resources folder within the library. This folder can contain additional folders like data, Images, Scripts...
There is information on the web as well as here on the topic related to the using external file resources in CDT Eclipse: C/C++ and H files located somewhere else in the files system. All the described methods run along two methods:
creation within the project space the virtual linked files which point to
the locations of the actual files without copying them
adding the location of the external referenced resource in the
Project->Properties->C/C++ general->Paths and Symbols and related
Project->Properties-> C/C++ Build (link folders and includes)
I am not sure if the 1st method is always enough without adding the 2nd, but seems the 2nd builds well without the 1st.
My question is about a comparison of the two. Are those methods intended to be used similarly or each one is preferred in some cases?
Is each method self sufficient without applying the other?
This forum thread
https://www.eclipse.org/forums/index.php/t/1087314/ suggests that for the include files the 1st method might not even be sufficient as the Build Settings should still be updated (2nd method) to include the linked H files...then may be the 1st method is irrelevant?
You would typically use the first method if you want to edit the externally-located files as part of your work on the project, and the second method if they're just dependencies that you use without modifying.
On a technical level, the difference is that with the first method the files will be part of the project model, and so will e.g. show up as candidates in Open Resource, while with the second method they wouldn't. Another difference is that with the first method, the files are indexed independently, while with the second method the files are only indexed by virtue of being included by files in your project (so e.g. .cpp files in those directories typically wouldn't be indexed with the second method at all).
Update: answers to questions from the comment
Is the 1st method sufficient enough in all cases without updating Paths and Symbols Property ?
No, if there are header files located in the linked directory that are included by files in your project using include paths that are not relative to the current directory (so not just #include "foo.h" in the same directory, #include "../foo.h" in a child directory, etc., but #include <bar/foo.h> in some other directory), you still want to specify those include paths in Paths and Symbols.
CDT's indexer does have an "Allow heuristic resolution of includes" option (specified in Preferences -> C/C++ -> Indexer) that may allow you to avoid adding the paths to Paths and Symbols, but note that (1) this affects the indexer only, not the build (which may be fine if you're using your own makefiles for the build), and (2) as it's heuristic, it's not perfect, e.g. if you have headers with the same name in different directories it can get confused. For best accurracy, I recommend unchecking "Allow heuristic resolution of includes", and always specifying include paths explicitly.
Also can the 2nd method be sufficient in itself if referenced files to be used AS IS without modification?
I don't see why not.
I've recently made a foray into building Linux-based embedded systems, a far cry from my usual embedded stuff where I have total control over everything.
As part of that, I'm looking into the Yocto/bitbake/OpenEmbedded build system.
There's one thing I'm grappling with and that's the layering concept, so I'm trying to both figure out the way in which layers use/affect other layers.
From my understanding to date, a .bb recipe file uses require to simply include another file, similar to C's #include "myheader.h" which generally looks locally.
A .bbappend file in an "upper" layer will auto-magically include the base file then make changes to it, sort of an inherent require.
In contrast, the inherit keyword looks for a .bbclass class file in much the same way as it locates the .bb files, and inherits all the detials from them (sort of like #include <stdio.h> which, again generally, looks in the system area(a)).
So the first part of my question is: is my understanding correct? Or am I being too simplistic?
The second part of my question then involves the use of BBEXTENDS in the light of my current understanding. If we already have the ability to extend a recipe by using require, what is the purpose of listing said recipes in a BBEXTENDS variable?
(a) Yes, I'm aware they're both totally implementation dependent in terms of where the headers come from, I'm simply talking about their common use.
The learning curve for Yocto is different than other building systems, that's why I understand your confusion. But trust me, this is worth it. Your questions are related to BitBake so I recommend the BitBake User Manual. Just ensure that you're reading the same version as your poky revision.
require and include.
require is similar to include and can be compared to #include from C and C++ just like you have written.
Although generally both of them should be used to add some extensions to a recipe (*.bb) which are common to some amount of recipes (simply - can be reused).
For instance: definitions of paths, custom tasks used by couple recipes. The common purpose is to make recipe cleaner and separate some constants for re-usage.
The very important thing -> difference between include and require (from BitBake manual):
The include directive does not produce an error when the file cannot be found. Consequently, it is recommended that if the file you are including is expected to exist, you should use require instead of include. Doing so makes sure that an error is produced if the file cannot be found.
As a result: when you include a file to *.bb and it hasn't been found, the BitBake will not raise an error during parsing this recipe.
If you would use require, the error will be raised. You should use require when the pointed file must exist because it contains important variables/tasks that are mandatory to process.
*.bbappend mechanism.
In the case of *.bbappend - it's very powerful. The typical usage is whey you are adding some custom modifications to the recipe from other layer (located above layer where original recipe is) by *.bbappend because (e.g): you are not the maintainer of original recipe or the modifications are only used in your project (then it should be located in your meta-layer). But you can also bbappend the recipe on the same layer. BitBake parses all layers and then 'creates' an output and executes it. More in chapter Execution from BitBake man.
inherit.
The inherit mechanism can be used to inherit *.bbclass where common tasks for some specific purpose are defined so you don't need to write them on your own, e.g: you use inherit cmake or inherit autotools to your recipe when it needs to provide output for sources that are built correspondingly by CMake (and you have CMakeLists.txt defined) or autotools (Makefile.am etc.).
The definitions of classes provided by OpenEmbedded are located under /meta/classes/ if you are using Yocto release with poky.
You can check them and you will see that for example autotools.bbclass has defined (among others) task: autotools_do_configure() so you don't need to write it from the scratch.
However, you can redefine it in your recipe (by just providing your own definition of this function). If the recipe can't be changed, then you can simply create a *.bbappend file and write your own function do_configure() which will override the function from *.bbclass. Just like in OO languages such as C++ or Java.
I'm trying to come up with a way to make it easy to switch out our "mock" data services and our live ones. Basically, we'll have live servers with real web services, but for whatever reason, a developer may want to load data from static files (file urls).
I figured I would solve this problem by creating categories that override the methods that fetch the data, thus leaving original code untouched (it has no concept of the "mock" data). I don't want to litter my code with #ifdef.
I can put an #ifdef at the very beginning of each file that has categories in it, and I can set a custom flag in the configuration settings, but I'd rather just have a way to include or exclude the files depending on the configuration. Is that possible? How do you solve this problem?
See http://lists.apple.com/archives/xcode-users/2009/Jun/msg00153.html
The trick is to define EXCLUDED_SOURCE_FILE_NAMES in the configuration you want to exclude the files from, and set the value of that custom build setting to a list of the file names (or a pattern that matches those, and only those, file names).
I would recommend creating two targets one of which has the mock categories included and another one which does not.
When you want to test, just build the target containing the mock categories. Everything else can remain identical.
If you would like to add a file but do not wont to compile it. Go to (for all your targets) project>build phases>compile source and take out the file that you do not want to compile.