Clarify #include policy and make usage consistent#2369
Conversation
| ``OpenEXRCore``, ``OpenEXRUtil``, ``Iex``, ``IlmThread``), not in a | ||
| single common ``OpenEXR`` folder, they are included internally as bare | ||
| files, without a ``OpenEXR/`` subdirectory. This intentionally differs | ||
| from the installed layout. |
There was a problem hiding this comment.
Would it be worth mentioning how OpenEXR includes Imath? Some user-facing header files do #includes of Imath without the prefix,, so when compiling against OpenEXR, it's always necessary to include the Imath folder itself.
(It does seem like this section conflates the library's internal design with how the application code should use the library. Perhaps a separate section on 'building code against OpenEXR' would be valuable, particularly for projects that aren't built with CMake)
|
@peterhillman, I split the header section in the install instructions into two, one for application code, here: and separate section addressing the layout of headers within the OpenEXR source tree: |
This explains the OpenEXR policy regarding the "OpenEXR/" subdirectory
for include files: headers are installed under the "OpenEXR"
subdirectory, and the library supports application code that uses
either the bare header or the "OpenEXR subdirectory, i.e either one
of:
#include <ImfHeader.h>
#include <OpenEXR/ImfHeader.h>
Both cmake config and pkg-config add -I$include and -I$include/OpenEXR
as compilation args.
This policy is explained for users in the "Header Layout and #include
Policy" section in website/install.rst.
Internally, all library and tool source includes bare headers, without
the "OpenEXR" since the source tree maintains headers local to each
library, not in a common OpenEXR directory. The only exception is code
in the source tree that is expected to mimic example application code.
Internally, all library and tool source includes files via quotes ""
when the header in question is either in the local directory or is one
of the public headers installed in the OpenEXR. Others are included
via brackets <>. Previously, this was inconsistent. Imath headers
are included via <> because they come from another project.
Signed-off-by: Cary Phillips <cary@ilm.com>
Signed-off-by: Cary Phillips <cary@ilm.com>
Signed-off-by: Cary Phillips <cary@ilm.com>
cary-ilm
merged commit 662ec14
into
AcademySoftwareFoundation:main
2 participants
This explains the OpenEXR policy regarding the "OpenEXR/" subdirectory for include files: headers are installed under the "OpenEXR" subdirectory, and the library supports application code that uses either the bare header or the "OpenEXR subdirectory, i.e either one of:
Both cmake config and pkg-config add -I$include and -I$include/OpenEXR as compilation args.
This policy is explained for users in the "Header Layout and #include Policy" section in website/install.rst.
Internally, all library and tool source includes bare headers, without the "OpenEXR" since the source tree maintains headers local to each library, not in a common OpenEXR directory. The only exception is code in the source tree that is expected to mimic example application code.
Internally, all library and tool source includes files via quotes "" when the header in question is either in the local directory or is one of the public headers installed in the OpenEXR. Others are included via brackets <>. Previously, this was inconsistent. Imath headers are included via <> because they come from another project.
This should address #1095