« Return to Thread: Most trivial example - failure

Re: Most trivial example - failure

by Smith Jack (Ext. - UGIS - UniCredit Group) :: Rate this Message:

>> David Piepgrass wrote:
> >> >From the very beginning I am confused.
> >>
> >> What is a module ? Why is the %module declaration needed
> ? What is
> >> it telling swig to do ?
> >
> I have added a bit more about this to the docs for the next
> version, but in the old docs, it is covered here:
>
> http://www.swig.org/Doc1.3/Java.html#module_packages_classes
> and it applies equally to C#.

Except it doesn't actually explain what a 'module' is.
"The SWIG %module directive specifies the name of the Java module",

What's a "Java module" ? (Sorry, I'm not a Java develper), is that the
same thing as a .jar file (or a C# .dll) ?

>
> > I have only used SWIG-C#. In SWIG-C# the module name is the
> name of the static class that contains wrappers of all global
> functions and variables. Also, if you use more than one
> module, each one needs a different name.
> >
> >> Why am I hash-including and percent-including the same file ?
> >> If I hash-include, surely swig now knows about the class,
> why would I
> >> need to tell it again ?
> >
> > I agree, this is poorly explained. SWIG follows %include
> directives but it ignores #include directives. %{ ... %}
> blocks are inserted verbatim into the .cxx wrapper file, but
> they are otherwise ignored by SWIG.
> >
> Actually the beginning of the basics chapter describes this,
> in particular http://www.swig.org/Doc1.3/SWIG.html#SWIG_nn6
> mentions that #include is not followed and why. It is also
> mentioned here:
> http://www.swig.org/Doc1.3/Preprocessor.html#Preprocessor_nn2.

Unfortunately neither of these explain what I must assume is meant,
namely, that the percent-include is a SWIG directive which behaves
similarly to C/C++ include in that it allows a SWIG user to re-use the
function prototype already available in the specified file, rather than
duplicating the prototype within the SWIG interface file.

A simple example could have been provided to clarify this.

Given the following header file:

/* File : example.h */
double g_global = 3.0;
/* Compute factorial of n */
int fact(int n);

One would reasonably expect that an equivalent SWIG interface file would
look like this:

/* File : example.i */
%module example
extern double g_global;
extern int fact(int);

but this could also be written like this, using SWIGs %include
directive:

/* File : example.i */
%module example

%include "example.h"

This is not at all difficult to explain, and the example makes it very
clear what the percent-include is doing.

Then an explanation of why the hash-include is needed (because
percent-include does not follow any hash-includes present in the
specified file)

>
> >> Where is the definitive list of swig reserved words and
> their meanings ?
> >> This does not seem to appear anywhere in any documentation
> I can find
> >> on swig.
> >
> > All SWIG-specific reserved words start with %... the ones
> that I can
> > think of are
> There is no single list, they are documented throughout.

This is not how technical documentation is normally structured.
Technical documentation has a 'standard' structure for a reason.

> As
> David mentioned all the SWIG directives begin with %, so just
> don't use anything starting with % if you are thinking of
> defining any macros.

OK, good suggestion, but it doesn't help at all since I had no idea
until I execute SWIG whether or not my choice of tokens is a reserved
word or not, and then I get a cryptic error, and am left wondering what
I've done wrong.

> I suggest the C approach of using
> capital letters for any macro names with some unique prefix.

Hey, good idea.

------------------------------------------------------------------------------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
Swig-user mailing list
Swig-user@...
https://lists.sourceforge.net/lists/listinfo/swig-user

« Return to Thread: Most trivial example - failure