Re: [boost] Boost.Tests: Unit test defines own main() function, why?

From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2007-12-21 02:27:31

"Jens Seidel" <jensseidel_at_[hidden]> wrote in message 
news:20071219090237.GA13691_at_imkf-pc073.imkf.tu-freiberg.de...
>> >  * According to 
>> > http://lists.boost.org/Archives/boost/2007/05/121601.php
>> >    linkers don't look into libraries (either static or dynamic) to
>> >    find main so that unit tests cannot be cimpiled as shared library.
>>
>> They do. On *nix platforms you can put main both in shared and static 
>> libs. On
>> NT only static. This was a source of inconsistency till 1.34.1, so 
>> starting
>> that release I've removed main from shared library builds on all 
>> platforms.
>
> And why are static and shared libraries handled differently? Why not
> just removing main also from static libraries?

1. For backward compartibility
2. For enhanced usebility in many cases. For people producing a lot of unit 
tests adding extra function main()
implementation is unnnecessary burdan (not mentioning that they will have to 
actually learn how implement it properly.
3. In many (if not the most) cases function main() handling is hidden 
completely from the users and usage and both usage variants behave pretty 
much the same. The only difference is presence of an extra macro 
BOOST_TEST_DYN_LINK.

> Should code really behave
> differently depending how it is linked (which is just a build
> configuration)? Do there exist other (non-Boost) libraries which do such
> stuff?

You comming to this from *nix prospecive. On NT dll and lib are two quite 
different ball games. Boost.Test opted to be consystent in between 
platforms.

>> It's not a bug. It's a feature. ;) Starting 1.34.1 main() doesn't reside 
>> in
>> shared libs.
>
> Is this change documented? Where can I find the Changelog?

In svn I guess.

> Did you also consider using a stable ABI (application binary interface, 
> would allow a
> binary to be used with different library version without need to
> recompile)

I sugest I write Boost.Test using C? In Boost.Test  a lot of staff happends 
in headers. We might find it difficult.

> or API (application programming interface, no need to change
> the source code to be able to compile against a new version of a
> library) (at least some time in the future)

I do not plan any changes that should break backward compartibility. 1.34.1 
did break it for very small number of use cases, which where never 
officially supported in a first place (plus I believe 1 tool was found 
unsafe and the interface was changes).

> which would make
> incompatibilities between shared and static libraries impossible and
> simplifies using different versions of Boost a lot? Whenever I try
> another Boost version existing code fails to compile or link ...

I am sure we will be able to figure it out. As far as i know there is no 
problem compiling/linking Boost.Test.

> The problem is that the example in the official documentation (which is
> (or should be) on www.boost.org not somewhere outside) just contains:
> "the Unit Test Framework is responsible for supplying function main()"
>
> Even if you consider that to be outdated (again: Why do you not update
> it??????) you should assume that most code arround does not provide
> main() and fails that's why starting with recent versions.

I did. And it deosn't fail for:

1. Users linking with static library
2. Users using included version
3. Users linking shared library and relying on automatic registration.

Only those who employ shared library and manual registration had an issue. 
Which is very easily resolve on all the cases.

> According to the updated documentation
> (http://www.patmedia.net/~rogeeff/html/utf/user-guide/test-runners.html)
> using the static library results in
>
> int main(int argc, char* argv[])
> {
>  return unit_test_main(argc, argv);
> }

No, that page doesn't say it. You *may* use it like this if you opt, but by 
default function main() reside in library and you don't need to implement 
one.

> whereas the shared library uses
> int unit_test_main( bool (*init_unit_test_func)(), int argc, char*
> argv[] );
>
> How could I define my own main function which is compatible with shared
> and dynamic libraries? unit_test_main has different signatures!?

1. shared and dynamic libs are comparitble ;)
2. Don't define init function at all. Employ automated registration 
facilities. And you don;t need ot care about test runner function signature.
3. The test runner  function signature is now the same for both static and 
dyanmic library (see svn). I am yet to update the updated docs ;)

> Probably I have to define BOOST_TEST_MAIN and let Boost create main.
> Let's hope this works for all linking options (shared/static).

It will if you are using autmatic registration facility.

>> In any case Boost.Test supports
>> what you want. In many, many cases you don't need init_.. function 
>> anymore and
>> boost test provides a way for users to get away without it and function 
>> main()
>> as well both with static and shared library usage variant of the UTF. If 
>> you
>
> OK. This is probably preferred.
>
>> prefer to define main youself and invoke init function you can do it as 
>> well
>> with shared library variant.
>
> The main problem is that I miss a porting guide. Is there a need to change
> the code, are some changes suggested, others required? How do I ensure

In many case no changes are required. It should work as is.

> that this changed code is compatible with as many versions of Boost as
> possible?
>
> I have really problems ignoring
> http://www.boost.org/libs/test/doc/components/utf/index.html as I
> consider this the offical documentation for Boost.Test. But it
> contradicts in some parts with your updated one!

Yes, the version on boost.org is very old. Docs writting take as much time 
(if not more) as actual development.

>> Please look for more details here:
>>
>> http://www.patmedia.net/~rogeeff/html/index.html
>>
>> Please let me know if there is any issues still.
>
> Problem with your updated documentation:
> http://www.patmedia.net/~rogeeff/html/utf/user-guide/usage-variants/static-lib-variant.html
>
> <quote>
> For a test module to be able to link with prebuilt library, the flag
> BOOST_TEST_ALTERNATIVE_INIT_API has to be defined both during library
> and a test module compilation.
> </quote>

> Hm, strange. Above I read that I can optionally define
> BOOST_TEST_ALTERNATIVE_INIT_API or not. Maybe you want to inform that
> BOOST_TEST_ALTERNATIVE_INIT_API needs to be (un)defined for both -
> compiling the library and a test module compilation, e.g. it is invalid
> to compile the first with this macro defined and the test module
> without?

I might need to rephrase it. The idea is that if you opted to use 
alternative API you neeed to define this flag both during library and test 
module compilation.

> http://www.patmedia.net/~rogeeff/html/utf/user-guide/usage-variants/dynamic-lib-variant.html
> <quote>
> This variant requires you to define the flag BOOST_TEST_DYN_LINK either
> in a makefile or before the header boost/test/unit_test.hpp inclusion.
> </quote>
>
> Is there really a need to define BOOST_TEST_DYN_LINK or does it just
> simplify linking on the proprietary win32 platform?

Really, really ;)

> Again: Why are
> static and shared libraries handled differently? It shouldn't matter!

It does on windows.

Gennadiy