Carl uses his laptop for private use and work. He works at home, while travelling on a train, or at the office. He uses the following hardware:
When Carl does home-office he uses Skype, a SIP application, and a H.323 application (e.g. Ekiga for both SIP and H.323) to provide VoIP connectivity to his collegues and be reachable via a phone number that is not his private phone number. To provide the best sound quality he wants to use his USB headset when it's connected. If the headset is not connected he wants to be able to answer calls with the built-in speakers and microphone. When he then connects the headset, while in a call, he wants the sound to migrate automatically to the headset.
When at work, he wants to use the microphone and speakers of the monitor for VoIP applications. If he plugs a headphone in the 3.5mm jack of the laptop, he'd like to use that as the output device. On unplugging the headphone jack the output should migrate to the monitor again.
Event sounds (this includes ringing sounds of VoIP applications when being called) should go to
Ami has her desktop computer on a desk in the living room. The internal HDA soundcard is connected to the monitor speakers via the 3.5mm front output jack and to high quality active speakers via the 3.5mm back output jack. She also has headphones with 3.5mm connectors which she can plug into either the headphone jack of the desktop or the headphone jack of the monitor. A USB webcam with built-in microphone is attached, providing the only microphone of this system, for use with Skype. The nearby TV is attached to the graphics card via an HDMI cable and can provide stereo audio output.
For most of her time at the computer, she only requires event sounds and the audio of web videos on her monitor speakers. If she wants to switch to higher quality playback, she turns on the active speakers and migrates the music and video audio to the active speakers while event sounds stay on the monitor speakers. To watch a DVD or some of her videos she uses the TV and either wants to use the TV speakers or the active speakers.
There are two types of #include statements: #include <foo.h> and #include "foo.h".
Say we have the file xyz.h in /usr/include/mylib/ that contains the following:
The preprocessor will search for the file header1.h in all the paths given as -I arguments and then replace the line with the contents of that file.
For line 2 the preprocessor tries to use the file /usr/include/mylib/header2.h first and if it does not exist search for the file like it did for header1.h. The important part to note here is that the preprocessor does not look in the directory of the source file that includes xyz.h but in the directory where xyz.h resides.
Now, which include statement is the one to use? After all you can specify every directory you want using -I and thus could use #include <...> everywhere.
Rationale: The header files of external libraries are obviously not in the same directory as your source files. So you need to use angle brackets.
Headers of your own application have a defined relative location to the source files of your application. Using KDE4's cmake macros your source directory is the first include switch to the compiler and therefore there's no difference in using angle brackets or double quotes. If you work with a different buildsystem that does not include the current source directory or disable CMAKE_INCLUDE_CURRENT_DIR then all includes (inside your application) using angle brackets will break.
Ideally the buildsystem would not need to specify -I<source directory> though as that can break with library headers that have the same filename as a header of your project (i.e.: If a library has the header file foo.h and your project has a different file with the same filename the compiler will always pick the header from your project instead of the one from the library because the source directory of the project is specified first.)
Rationale: The header files of external libraries are obviously not in a fixed location relative to your source files. So you need to use angle brackets.
Headers of your own libraries have a fixed relative location in the filesystem. Therefore you can use double quotes. You should use double quotes because otherwise the include statement could include a different header file than expected. An example how angle brackets can break the build:
/usr/include/libxyz/xyz.h includes foo.h using angle brackets and expects to have it replaced with the contents of the file /usr/include/libzyx/foo.h. Assuming there's another library that also ships a foo.h file in the directory /usr/include/anotherlib/. If the application that uses both libraries compiles with "g++ -I/usr/include/libxyz -I/usr/include/anotherlib ..." libxyz will work as expected. If the application compiles with "g++ -I/usr/include/anotherlib -I/usr/include/libxyz ..." the header xyz.h will include the file /usr/include/anotherlib/foo.h instead of the file that is shipped with libxyz. The same problem can appear if an application has a header file of the same name as a library and specifies -I./ as the first include directory.
If you use subdirectories for the installed header files you need to have the exact same directory structure for the headers in the source directory. Example: /usr/include/libfoo/ contains the directory bar. In libfoo resides the header header1.h, in libfoo/bar the file header2.h. The latter depends on the former so it includes it using
#include "../header1.h"If the source directory structure of the library is not the same (in this case: header2.h in a subdirectory of the directory where header1.h resides) this obviously will break.