Re: [pdf-devel] Unneeded macros in the public header

[Aleksander Morgado]

Sorry for the long email :-)

>    Is there any good reason to generate the PDF_DEBUG_* and PDF_ASSERT_*
>    macros in the public pdf.h header?
> 
> Yes.  Currently these macros are available to the library user and are
> documented in the reference manual.  The rationale is to ease the
> debugging of problems while using the library.
> 

Humm.. Not really sure if that's so useful. Whenever the library is
distributed out there, it won't be compiled with the configure options
which enable those macros, so PDF_DEBUG_* macros for example will do
nothing. We don't even use them in our unit tests, I believe.

Also, enabling or disabling those macros actually depend on the #defines
we have in our config.h, which is not distributed.

Thus, if a given library user wants to use those macros, she needs to
prepare her own config.h (for example) to be included before pdf.h and
define the proper things.

Probably this could also apply to other things, actually. For example,
in order to use the OS-built-in bignum implementation (and avoid
libgnupdf's one), the library user currently needs to #define
PDF_USE_BUILTIN_64BIT_SUPPORT herself before including pdf.h. This
actually doesn't make much sense. The proper way of doing it, IMO, would
be to generate a different pdf.h depending on the OS where the library
is compiled. For example, if library is compiled in an OS where bignum
support is already in the OS, the pdf.h would include the macros to use
them; and if the library is compiled in an OS with no bignum support,
our own implementation's API methods would get included in pdf.h. At the
end, the API is the same, just the implementation behind changes (in one
case they are macros, in the other case functions in libgnupdf).

Look at this example. I configured, compiled and installed libgnupdf in
my GNU/Linux which of course has already built-in support for 64bit
numbers. Then I created this test:

#include <stdio.h>
#include <pdf.h>

int main(int argc, char **argv)
{
    pdf_i64_t num;
    pdf_i64_assign_quick (&num, 3, NULL);
    return 0;
}

And tried to compile it:
$> gcc -o test `pkg-config --cflags --libs libgnupdf` test.c
/tmp/ccE3gXyg.o: In function `main':
test.c:(.text+0x21): undefined reference to `pdf_i64_assign_quick'
collect2: ld returned 1 exit status


The issue here is that libgnupdf was compiled with the OS-built-in
support for bignums, and thus, MACROS should be used. Then, I use the
library and instead of getting pdf_i64_assign_quick() as a macro, the
compiler tries to look for the actual libgnupdf method for bignum
support; basically because we did not define
PDF_USE_BUILTIN_64BIT_SUPPORT before the pdf.h. Now, if we modify the
example and add the #define before including pdf.h:

#include <stdio.h>
#define PDF_USE_BUILTIN_64BIT_SUPPORT 1
#include <pdf.h>

int main(int argc, char **argv)
{
    pdf_i64_t num;
    pdf_i64_assign_quick (&num, 3, NULL);
    return 0;
}

And I try to compile it again:
$> gcc -o test `pkg-config --cflags --libs libgnupdf` test.c
test.c: In function ‘main’:
test.c:10: warning: dereferencing ‘void *’ pointer
test.c:10: error: invalid use of void expression
test.c:10: warning: dereferencing ‘void *’ pointer
test.c:10: error: invalid use of void expression

Which gives a different error now. Now we are really using the macros
that we expected for bignum support, and the compiler now cries because
we are dereferencing some void * pointers (when using the macros, the
pointer variables are interpreted as void *, I guess, as not really
specified what they are, so explicit casting is needed inside the macro
implementations).

In a brief, the generated pdf.h should not include any #ifdef XXX where
XXX is a #define from our config.h. And if we have some of them, we
should include them properly at the beginning of the pdf.h.

Cheers,
-Aleksander