Re: [Edoc-main] Installation problems

[Brendon C. <br...@ch...>]

 > I'm really, really anxious to try edoc out, but I'm having trouble.
 > First, it doesn't compile on Mac OS due to a lack of libbfd.

I am sorry that building it has been such an ordeal...

I cant do much about Mac OS since i don't have access to it anywhere, 
however i will install FreeBSD on a virtual machine and fix those 
problems for the next release which should be coming out in the next 
month and fixes a bug with the reporting of exception for virtual 
functions (Should have been much earlier but i have had a slight detour 
to playing an MMORPG instead :-) )

I have only tested EDoc++ with Linux, NetBSD and partially with cygwin.

> Interestingly, configure checks for libbfd but doesn't consider its 
> absence a failure, even though the build will fail if libbfd is not 
> there. This is probably a bug.

If libbfd is not on the system, it should just disable certain features. 
I.e. Embedding EDoc++ data in binary files which is a convenience thing.



> Then I switched to FreeBSD. It took a little trickery to get the build 
> to work. I had to create a symbolic link to 
> /usr/local/lib/libpython2.5.so <http://libpython2.5.so>, since the edoc 
> build only looks for libpython. Then, my configure invocation looks like 
> this:
> 
> LDFLAGS=-L/usr/local/lib CPPFLAGS=-I/usr/local/include/python2.5 
> LIBS=-lpthread ./configure
> 
> Setting --with-libpython doesn't work, since you can't set it to 
> /usr/local due to the location of the headers.
> 

There is a slight modification I have put into the configure script for 
allowing this. You should be able to specify both the header and lib 
dirs separately using a ':'

I.e.

./configure --with-libpython=/usr/local/include/python2.5:/usr/local/lib


> Then the build failed because bfd_utils.cpp does not include 
> <sys/stat.h>, even though it uses struct stat. 

That is a bug, thanks for the report.

> It also fails while 
> building gcc due to conflicting declarations of the function strsignal, 
> which I resolved by commenting the edoc-included one out.
> 
hmm. I dont remember using strsignal at all in my code/modifications of 
GCC so it must be a part of the official GCC source. I know different 
distributions often maintain patches of official source tarballs as part 
of their ports/pkgsrc/rpm source repositories.

This may be one of those things that is done for FreeBSD. I would be 
interesting to try and compile the original GCC tarball without any 
EDoc++ patches applied. I assume that it would give the same results.

There is little i can do about this particular problem at the moment 
except to document it. I cant maintain a set of patches against GCC for 
each platform it doesn't compile out of the box for.

There were plans to make the EDoc++ GCC patch a GCC "plugin" instead, 
however the GCC maintainer (last time i checked) dont want to add this 
feature to GCC for ambiguity with licensing issues. If this could happen 
it would mean i don't need to patch GCC or even build GCC as part of 
EDoc++, but alas politics gets in the way of progress it seems...


> Finally, with edoc successfully built on FreeBSD I get the following at 
> every invocation:
> 
> $ edoc Connection.hpp
> Filed opening file: Connection.hpp
> Reason: Unknown file type.
> $
> 
> It doesn't matter what input I give edoc. It will tell me that the file 
> type is unknown in every instance, without fail, even if the input is a 
> directory.
> 

EDoc++ does not process source files directly, rather it uses the 
modified GCC to compile source files while annotating data about what is 
in the code, and then processes the data generated by GCC.

Look at the basic usage section of the EDoc++ manual:
http://edoc.sourceforge.net/EDocManual/ch06.html

So for you example, i would assume you have some main.cpp file that uses 
this Connection.hpp header. To used EDoc++ with this it might look like:

Assuming main.cpp uses this header...

start_edoc.sh
EDOC -> g++ -fedoc-file=myapp.edc main.cpp -o myapp
EDOC -> edoc --format simple myapp.edc


Just to describe what is going on here...

* start_edoc.sh : Simply sets up a shell that has all environment 
variables set to use the EDoc++ tool chain (I.e. patched GCC)

* g++ -fedoc-file=myapp.edc main.cpp -o myapp
Compiles main.cpp into an executable: 'myapp', however also annotates 
information about function callgraph and exceptions. This annotation is 
placed in the file 'myapp.edc'

* edoc --format simple myapp.edc
This gets EDoc++ to look at the data and generate a 'simple' format 
information about the exception propagation for each function.

That should get you started...