AW: Cleaning up include file inconsistencies

[Richard Levitte]

On Sat, 06 Jul 2019 11:50:48 +0200,
Dr. Matthias St. Pierre wrote:
> 
> There are more oddities in the organization of the internal header files.
> 
> 1) It appears to me that there are three different levels of internal header files
> 
>  - headers in `include/internal`

For internal things that we want to make available for both libcrypto
and libssl (i.e. they are exported in libcrypto.so)

>  - headers in `crypto/include/internal`

For internal things that we only want available inside libcrypto
(i.e. they are NOT exported in libcrypto.so)

>  - headers in `crypto/<package>` along with the source files

For things that are private to that sub-system (sorry, "package"
doesn't sound right)

> Having such a finegrained distinction is not the problem, but (at least to me)
> it is not entirely clear which include file goes into which directory.
> 
> 2) Some of the header files carry an `_int.h` suffix while others not,
> for seemingly no particular reason.
> 
> 	~/src/openssl$ find -name '*_int.h'
> 	./crypto/crmf/crmf_int.h

Should have been named crmf_locl.h

> 	./crypto/include/internal/err_int.h
> 	./crypto/include/internal/ess_int.h
> 	./crypto/include/internal/ec_int.h
> 	./crypto/include/internal/rand_int.h
> 	./crypto/include/internal/store_int.h
> 	./crypto/include/internal/asn1_int.h
> 	./crypto/include/internal/modes_int.h
> 	./crypto/include/internal/cryptlib_int.h
> 	./crypto/include/internal/bn_int.h
> 	./crypto/include/internal/evp_int.h
> 	./crypto/include/internal/x509_int.h

The reason for this is to avoid confusion between headers in
crypto/include/internal and headers in include/internal.  It's not
quite as necessary as all these names seem to suggest, but we do have
these as an example:

    : ; find . -name 'err*.h' | grep /include/internal/
    ./include/internal/err.h
    ./crypto/include/internal/err_int.h

> 	./crypto/cmp/cmp_int.h

Should have been named cmp_locl.h

> 	./crypto/x509/pcy_int.h

Should have been named pcy_locl.h

> In particular for the headers the `include/internal` folder this suffix
> is superfluous, because these files are (or should be) included via
> relative paths. So instead of
> 
> 	#include <openssl/evp.h>
> 	#include "internal/evp_int.h"
> 
> It could just be
> 
> 	#include <openssl/evp.h>
> 	#include "internal/evp.h"

In most cases, you're right.  I suspect "_int" was habitually added to
ensure we know exactly where that header comes from.

Me, I'm wondering if it wouldn't be clearer if we renamed
crypto/include/internal -> crypto/include/crypto, and thereby did
this:

    #include "crypto/evp.h"

That, to me, is much clearer than the "_int" suffix.

Cheers,
Richard

-- 
Richard Levitte         levitte at openssl.org
OpenSSL Project         http://www.openssl.org/~levitte/