Most trivial example - failure

[Smith Jack (Ext. - UGIS - UniCredit Group)]

I am trying to understand how SWIG behaves.

I have a C++ project which creates a library
The project contains the class header and cpp files as follows.

// ------------- File a_lib.h
class a_lib {
public:
        a_lib(void);
       
        void func( );
};
-------------------------------
// ------------- File a_lib.cpp
a_lib::a_lib()
{
}

void a_lib::func()
{
           
}
-------------------------------

I also have a swig interface file as follows

/* File a_lib_swig.i */
%module a_lib_swig
%{
        #include "a_lib.h"
%}

%include "a_lib.h"


>From the very beginning I am confused.

What is a module ?  Why is the %module declaration needed ?  What is it
telling swig to do ?
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 ?
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.



------------------------------------------------------------------------------
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

[Smith Jack (Ext. - UGIS - UniCredit Group)]

>From the documentation

16 Working with Modules
When first working with SWIG, users commonly start by creating a single
module. That is, you might define a single SWIG interface that wraps
some set of C/C++ code. You then compile all of the generated wrapper
code into a module and use it.



What's a module ??   Is it a psuedonym for a (shared)library (as in
windows .dll, or *nix .so file)?

What do you mean "compile all of the generated wrapper code into a
module" ?
Do you mean compile the generated wrapper classes and link them together
along with the original classes that they wrap into a shared library?




------------------------------------------------------------------------------
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

[David Piepgrass]

> >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 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.

> 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

%module  : first line of your .i file
%include : include a file
%feature : modifies some aspect of SWIG's behavior
%typemap : see chapter 10
%apply   : copy typemaps from one type to another,
           unless the target type already has typemaps defined
%rename  : change name of something in target language
%ignore  : do not create a wrapper for a specific type
%template: instantiate a C++ template and wrap it
%insert  : insert code in .cxx wrapper file
%fragment: define a piece of shared code in .cxx wrapper file that
           is inserted only if it is requested by a typemap
%define...%enddef: multi-line #define

I think most other terms such as %newobject are not keywords, but aliases for features, e.g. in Lib/swig.swg you'll see

#define %newobject        %feature("new")

C/C++ reserved words are also reserved and have the same meaning as they do in C/C++.


------------------------------------------------------------------------------
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

[wsfulton]

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#.

> 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.

>> 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. 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. I
suggest the C approach of using capital letters for any macro names with
some unique prefix.

William

------------------------------------------------------------------------------
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

[Smith Jack (Ext. - UGIS - UniCredit Group)]

 

> > >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 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.

OK, that's interesting, but just opens up more questions.  
All what global functions and variables ?  
All those included within the hash-included files between the %{ and %}
delimiter ?
Or anything that SWIG decides is global (how do I know?) up until the
next use of the key-word %module ?


> > 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.

So, is it correct that anything found between the %{ ... %} will be
included verbatim ?

Are you saying then that the percent-include is using the specified file
as if it were providing the signature of the functions (as an include
file is used) to be wrapped by SWIG, instead of requiring the developer
to duplicate that information within the module definition file ?

That makes a bit of sense now, this is not at all clear from the
documentation.

>
> > 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 %...

Yes, I think that is documented, but a list of the available reserved
words are (e.g., the 'commands' available to me as a developer) is
missing.  This is a pretty significant deficite in the SWIG
documentation, and I am amazed nobody has bothered to construct some
kind of index.

> the ones
> that I can think of are
>
> %module  : first line of your .i file

Great (no offence), but what is it doing ??   What is the scope ?  what
'arguments' does it take ?
I keep seeing this type of construct:

%module(directors="1")

But I've yet to find any documentation which discusses what the
'directors' part means or why the number is "1"  (why the quotes, anyway
?).  

> %include : include a file
> %feature : modifies some aspect of SWIG's behavior %typemap :
> see chapter 10
> %apply   : copy typemaps from one type to another,
>            unless the target type already has typemaps  defined
> %rename  : change name of something in target language
> %ignore  : do not create a wrapper for a specific type
> %template: instantiate a C++ template and wrap it
> %insert  : insert code in .cxx wrapper file
> %fragment: define a piece of shared code in .cxx wrapper file that
>            is inserted only if it is requested by a typemap
> %define...%enddef: multi-line #define

Note to SWIG developers or contributors:  Any chance of putting together
a list like that above with some more thorough explanations, or at least
a hyperlink to where the topic is discussed within the documentation
>
> I think most other terms such as %newobject are not keywords,
> but aliases for features, e.g. in Lib/swig.swg you'll see
>
> #define %newobject        %feature("new")
>
So, here we have what looks like C/C++ syntax being used to control the
behaviour of SWIG, even though all SWIG 'commands' or reserved words are
suppsoed to begin with %.  How inconsistant is that !

> C/C++ reserved words are also reserved and have the same
> meaning as they do in C/C++.

What ????   How would that affect SWIGs behaviour,

------------------------------------------------------------------------------
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

[Smith Jack (Ext. - UGIS - UniCredit Group)]

 

>> 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

[David Piepgrass]

> > 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.

okay let's pick a word at random: "garbage". Is this a SWIG reserved word? Of course not, because it is not a C/C++ keyword and it doesn't start with %.


------------------------------------------------------------------------------
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

[Smith Jack (Ext. - UGIS - UniCredit Group)]

>
> > > 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.
>
> okay let's pick a word at random: "garbage". Is this a SWIG
> reserved word? Of course not, because it is not a C/C++
> keyword and it doesn't start with %.

So I know it's not a SWIG reserved word if it's not a C/C++ keyword ?

I can tell I am not explaining myself correctly, let me try again.

There appears to be no definitive list of SWIG directives.
Furthermore there seems to be no definition of the 'arguments' (required
or optional) to those directives, nor is there a concise definition for
what many (most) of the directives do.

As a simple example consider the %modules directive.  Where is the list
of possible 'arguments' to this directive.  I know that such arguments
exist, since I know of one such argument strictly by chance, it is the
'directors' argument, itself completely undocumented (from what I can
tell anyway?)  Where is the %modules directive itself explained (other
than in a tautology)

If I am wrong, a pointer would be greatly appreciated

------------------------------------------------------------------------------
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

[Josh Cherry]

On Thu, 18 Jun 2009, Smith Jack (Ext. - UGIS - UniCredit Group) wrote:

> So I know it's not a SWIG reserved word if it's not a C/C++ keyword ?

This seems to address that: http://www.swig.org/Doc1.3/SWIG.html#SWIG_nn7.

> I know that such arguments
> exist, since I know of one such argument strictly by chance, it is the
> 'directors' argument, itself completely undocumented (from what I can
> tell anyway?)

http://www.swig.org/Doc1.3/Python.html#Python_nn33 (for Python)

> Where is the %modules directive itself explained (other
> than in a tautology)

http://www.swig.org/Doc1.3/SWIG.html#SWIG_nn3
http://www.swig.org/Doc1.3/Python.html#Python_nn14 (for Python)

Check the relevant language documentation for other languages.

Your questions about %include, etc., are dealt with in an introductory way
in several places (e.g., http://www.swig.org/Doc1.3/SWIG.html#SWIG_nn3),
and in more detail at http://www.swig.org/Doc1.3/Preprocessor.html.  The
documentation could be improved, but I'm not sure why you're having so
much trouble finding stuff.

Josh


------------------------------------------------------------------------------
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

[Smith Jack (Ext. - UGIS - UniCredit Group)]

 
This wikipedia article helped me to understand SWIG's use of the term
"module".

http://en.wikipedia.org/wiki/Modularity_(programming)

May I suggest that this term be clearly defined early in the SWIG
documentation so that those of us who have never developed using COBOL,
RPG, PL/1, Ada, D, F, Fortran, Haskell, Pascal,ML, Modula-2, Erlang,
Perl, Python or Ruby (which apparently are familiar with the term as is
used) - a set which includes the worlds most popular programming
languages (Visual)Basic, C, C++, C# and Java - can at least start to
understand the SWIG documentation.

I'm still not certain what equivalent concept exists in those latter
languages, but I suspect that for C++, C# and Java the word 'class' is
an almost exact replacement.

As a reasonably seasoned C/C++/C# developer reading the SWIG
documentation is very difficult, since there are frequent misuse of
terms such as compile and module.

Examples:

"In a nutshell, SWIG is a compiler that takes C declarations and creates
the wrappers ...", here the use of the word 'compiler' is extremely
confusing and at odds with the classic definition of that word - see:
Paragraph 2 http://en.wikipedia.org/wiki/Compiler .  I would say that
SWIG is essentially an enhanced pre-processor (in the C/C++ use of that
term), not a compiler, since it does not output object files.

"Most operating systems and scripting languages now support dynamic
loading of modules."  I know of no 'major' operating system which allows
the dynamic loading of 'modules' (especially considering that the SWIG
usage of module is not an executable image, but essentially a 'class'
definition), but I know several operating systems which allow the
dynamic loading of shared object files (aka Dynamic Link Library) which
may contain any number of compiled 'modules'.

It is these types of inconsistancies which, for me anyway, have made
understanding SWIG extremely challenging.

I hope I don't sound like I'm being pedantic, or merely ranting. SWIG is
clearly a very powerful and useful too, and I have little choice but to
use it for the project I am on now.  I hope my comments are accepted in
the spirit they are intended, to help others like myself who are new to
SWIG learn it more efficiently.

------------------------------------------------------------------------------
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

[wsfulton]

Smith Jack (Ext. - UGIS - UniCredit Group) wrote:

>  
> This wikipedia article helped me to understand SWIG's use of the term
> "module".
>
> http://en.wikipedia.org/wiki/Modularity_(programming)
>
> May I suggest that this term be clearly defined early in the SWIG
> documentation so that those of us who have never developed using COBOL,
> RPG, PL/1, Ada, D, F, Fortran, Haskell, Pascal,ML, Modula-2, Erlang,
> Perl, Python or Ruby (which apparently are familiar with the term as is
> used) - a set which includes the worlds most popular programming
> languages (Visual)Basic, C, C++, C# and Java - can at least start to
> understand the SWIG documentation.
>
> I'm still not certain what equivalent concept exists in those latter
> languages, but I suspect that for C++, C# and Java the word 'class' is
> an almost exact replacement.
>
> As a reasonably seasoned C/C++/C# developer reading the SWIG
> documentation is very difficult, since there are frequent misuse of
> terms such as compile and module.
>
> Examples:
>
> "In a nutshell, SWIG is a compiler that takes C declarations and creates
> the wrappers ...", here the use of the word 'compiler' is extremely
> confusing and at odds with the classic definition of that word - see:
> Paragraph 2 http://en.wikipedia.org/wiki/Compiler .  I would say that
> SWIG is essentially an enhanced pre-processor (in the C/C++ use of that
> term), not a compiler, since it does not output object files.
>
> "Most operating systems and scripting languages now support dynamic
> loading of modules."  I know of no 'major' operating system which allows
> the dynamic loading of 'modules' (especially considering that the SWIG
> usage of module is not an executable image, but essentially a 'class'
> definition), but I know several operating systems which allow the
> dynamic loading of shared object files (aka Dynamic Link Library) which
> may contain any number of compiled 'modules'.
>
> It is these types of inconsistancies which, for me anyway, have made
> understanding SWIG extremely challenging.
>
> I hope I don't sound like I'm being pedantic, or merely ranting. SWIG is
> clearly a very powerful and useful too, and I have little choice but to
> use it for the project I am on now.  I hope my comments are accepted in
> the spirit they are intended, to help others like myself who are new to
> SWIG learn it more efficiently.

SWIG is an open source project and all the contributions, including the
documentation have been given by volunteers. Although the nearly 700
pages of documentation is of a much higher volume and quality compared
to most open source projects, it is far from being perfect and is
lacking severely in some areas. Many of your comments in previous
threads have been valid, but some indicate that you simply have not hd
the patience to read the documentation that is there. I havn't had time
to reply to all your comments, but have attempted to improve the docs on
modules with your comments in mind. You can view the recent commits
http://swig.svn.sourceforge.net/viewvc/swig/trunk/Doc/Manual/?view=log

and can even view the latest version online from
http://swig.svn.sourceforge.net/viewvc/swig/trunk/Doc/Manual/

starting here:
http://swig.svn.sourceforge.net/viewvc/swig/trunk/Doc/Manual/Contents.html

Given you are going through the docs with a fine tooth comb, please
submit a patch onto SourceForge with any corrections you feel are
necessary. Contributions from SWIG users such as yourself are the only
way it is going to get better.

Thanks
William

------------------------------------------------------------------------------
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

[Christian-128]

Disclaimer : I have never contributed a line to either swig code or documentation.

That being said, I couldn' disagree more with you about SWIG documentation.

I come from a mainly java world it seems to me that the "module" term is a pretty good one. The "class" word would certainly be inapropriate since there can be many classes generated from a SWIG module (most of them being bindings to C structures, and then the static entry class which delegates native call to another class)....

If I were you I'd just think of the module as a set of structures and functions that it makes sense to package together. (As for me wrapping libSVG and cairo it made immediately sense that I would have a cairo module and a SVG module).

I don't think either that compilers only produce bytecode (just think of compiling a regexp for instance). Calling SWIG a compiler gives much more credit to the information it is capable to gather about types and structures in order to generate bindings, hence it helps understanding what it does.

Just for any other framework out there I think it helps to have some experience in dealing with third party tools and investigating a little by yourself, but given that, I have experience with quite a few open-source java frameworks and libraries and I can tell you that SWIG documentation is one of the best I've seen (and as far as I know java is not even their main target).


Cheers


PS I do think you sound a little pedantic, pointing out wikipedia to make your point, but that's just my humble opinion.

------------------------------------------------------------------------------
Are you an open source citizen? Join us for the Open Source Bridge conference!
Portland, OR, June 17-19. Two days of sessions, one day of unconference: $250.
Need another reason to go? 24-hour hacker lounge. Register today!
http://ad.doubleclick.net/clk;215844324;13503038;v?http://opensourcebridge.org
_______________________________________________
Swig-user mailing list
Swig-user@...
https://lists.sourceforge.net/lists/listinfo/swig-user

[David Beazley-3]

>
> PS I do think you sound a little pedantic, pointing out wikipedia to  
> make your point, but that's just my humble opinion.
> ------------------------------------------------------------------------------

Especially when just about every other part of that wikipedia link  
(e.g., compiler phases, processing steps, etc.) seem to describe Swig  
fairly accurately.

-Dave


------------------------------------------------------------------------------
Are you an open source citizen? Join us for the Open Source Bridge conference!
Portland, OR, June 17-19. Two days of sessions, one day of unconference: $250.
Need another reason to go? 24-hour hacker lounge. Register today!
http://ad.doubleclick.net/clk;215844324;13503038;v?http://opensourcebridge.org
_______________________________________________
Swig-user mailing list
Swig-user@...
https://lists.sourceforge.net/lists/listinfo/swig-user

[David Piepgrass]

> May I suggest that this term be clearly defined early in the SWIG
> documentation so that those of us who have never developed using COBOL,
> RPG, PL/1, Ada, D, F, Fortran, Haskell, Pascal,ML, Modula-2, Erlang,
> Perl, Python or Ruby (which apparently are familiar with the term as is
> used) - a set which includes the worlds most popular programming
> languages (Visual)Basic, C, C++, C# and Java - can at least start to
> understand the SWIG documentation.
>
> I'm still not certain what equivalent concept exists in those latter
> languages, but I suspect that for C++, C# and Java the word 'class' is
> an almost exact replacement.

No. A SWIG module typically encapsulates many classes.

I admit that I do not understand SWIG modules well enough to use more than one of them. Fortunately, if you don't need more than one module, then you need not know almost anything about them. And if you don't understand modules well enough to decide whether you need more than one, then just use one module and forget about the matter!

I think you're trying too hard to understand SWIG by reading its documentation. Like many tools, SWIG is easier to understand by using it. Try to wrap some C/C++ code with it, and come back to the mailing list when you have a specific problem you can't solve.

> "In a nutshell, SWIG is a compiler that takes C declarations and creates
> the wrappers ...", here the use of the word 'compiler' is extremely
> confusing and at odds with the classic definition of that word - see:
> Paragraph 2 http://en.wikipedia.org/wiki/Compiler .  I would say that
> SWIG is essentially an enhanced pre-processor (in the C/C++ use of that
> term), not a compiler, since it does not output object files.

I disagree. Compiler is an appropriate term because SWIG parses code and outputs something in a completely different from the input. There are some programming languages whose "compilers" use C as their output language instead of machine language -- and we still call them compilers.

> "Most operating systems and scripting languages now support dynamic
> loading of modules."  I know of no 'major' operating system which allows
> the dynamic loading of 'modules'...
> I hope I don't sound like I'm being pedantic.

Typically one compiles a module into a DLL or 'shared object'. To say that the DLL is dynamically loaded and not the module sounds overly pedantic to me, but could be forgiven if you didn't realize that modules are typically 1:1 with DLLs. By the way, Microsoft sometimes refers to DLLs as 'modules'.

------------------------------------------------------------------------------
Are you an open source citizen? Join us for the Open Source Bridge conference!
Portland, OR, June 17-19. Two days of sessions, one day of unconference: $250.
Need another reason to go? 24-hour hacker lounge. Register today!
http://ad.doubleclick.net/clk;215844324;13503038;v?http://opensourcebridge.org
_______________________________________________
Swig-user mailing list
Swig-user@...
https://lists.sourceforge.net/lists/listinfo/swig-user

[Smith Jack (Ext. - UGIS - UniCredit Group)]

-- SNIP --  

> SWIG is an open source project and all the contributions,
> including the documentation have been given by volunteers.
> Although the nearly 700 pages of documentation is of a much
> higher volume and quality compared to most open source
> projects, it is far from being perfect and is lacking
> severely in some areas. Many of your comments in previous
> threads have been valid, but some indicate that you simply
> have not hd the patience to read the documentation that is
> there. I havn't had time to reply to all your comments, but
> have attempted to improve the docs on modules with your
> comments in mind. You can view the recent commits
> http://swig.svn.sourceforge.net/viewvc/swig/trunk/Doc/Manual/?view=log
>
> and can even view the latest version online from
> http://swig.svn.sourceforge.net/viewvc/swig/trunk/Doc/Manual/
>
> starting here:
> http://swig.svn.sourceforge.net/viewvc/swig/trunk/Doc/Manual/C
> ontents.html
>

I have been reading the documentation which is found here:
http://www.swig.org/Doc1.3/  which is where the SWIG front page
http://www.swig.org/doc.html, eventually leads to.

The link you have provided (to SWIG documentation within a subversion
repository) appears to contain significantly different documentation.
So different that sections present in the former version are either
renamed, renumbered or entirely missing from the latter.

I presume that the subversion version of the documentation is the most
up to date, and so will refer to that in the future.

Perhaps a link from the main SWIG page to the subversion version of the
SWIG documentation would help prevent further confusion.


> Given you are going through the docs with a fine tooth comb,

Only because I am trying to understand how to use SWIG.

> please submit a patch onto SourceForge with any corrections
> you feel are necessary. Contributions from SWIG users such as
> yourself are the only way it is going to get better.
>
 
Once I am able to understand SWIG well enough to contribute sensible
corrections I will do so.


------------------------------------------------------------------------------
Are you an open source citizen? Join us for the Open Source Bridge conference!
Portland, OR, June 17-19. Two days of sessions, one day of unconference: $250.
Need another reason to go? 24-hour hacker lounge. Register today!
http://ad.doubleclick.net/clk;215844324;13503038;v?http://opensourcebridge.org
_______________________________________________
Swig-user mailing list
Swig-user@...
https://lists.sourceforge.net/lists/listinfo/swig-user

[wsfulton]

Smith Jack (Ext. - UGIS - UniCredit Group) wrote:

>> and can even view the latest version online from
>> http://swig.svn.sourceforge.net/viewvc/swig/trunk/Doc/Manual/
>>

> I have been reading the documentation which is found here:
> http://www.swig.org/Doc1.3/  which is where the SWIG front page
> http://www.swig.org/doc.html, eventually leads to.
>
That is a copy of the documentation published with the current release.

> The link you have provided (to SWIG documentation within a subversion
> repository) appears to contain significantly different documentation.
> So different that sections present in the former version are either
> renamed, renumbered or entirely missing from the latter.
>
If you look at the svn logs, you'll see that the chapter ordering has
been changed, but other than that nothing significant has happened.

> I presume that the subversion version of the documentation is the most
> up to date, and so will refer to that in the future.
>
> Perhaps a link from the main SWIG page to the subversion version of the
> SWIG documentation would help prevent further confusion.

The subversion documentation is bleeding edge and is not necessarily
ready for general consumption or relevant to the latest release. It is
the best version for submitting patches against, but 1.3.39 patches
should apply well too. If you follow the bleeding edge links on the home
page it will take you to subversion. You can then navigate to the docs,
and I'd like to keep it that way. I was hoping that by pointing you to
trunk on subversion that you would know it is the latest development
version, I hope that clarifies any source of confusion.

William

------------------------------------------------------------------------------
Are you an open source citizen? Join us for the Open Source Bridge conference!
Portland, OR, June 17-19. Two days of sessions, one day of unconference: $250.
Need another reason to go? 24-hour hacker lounge. Register today!
http://ad.doubleclick.net/clk;215844324;13503038;v?http://opensourcebridge.org
_______________________________________________
Swig-user mailing list
Swig-user@...
https://lists.sourceforge.net/lists/listinfo/swig-user