Updating dll info in the User's Guide

Updating dll info in the User's Guide

[Joshua Daniel Franklin]

Gerrit and other dll-builders,

Thanks for the update on dll-building. I almost missed this one...
I was thinking "Why doesn't someone just update the documentation?"
then realized "Hey, I volunteered to do that, didn't I?"
(BTW, everyone--could I get heads-up about the User's Guide like David gets
about the FAQ?)

Here is some new text to replace the section at

http://cygwin.com/cygwin-ug-net/dll.html

that begins with "Unfortunately, the process for building a dll is, well,
convoluted. You have to run five commands, like this"
This is not the actual patch, I will submit one of those after
I verify that I've got the subject matter correct.
Please read carefully since I'm not an expert in this area and may have
mixed up some terminology or concepts.

--------Begin new text--------
Fortunately, with the latest gcc and binutils the process for building a dll
is now much simpler. Say you want to build this minimal function in mydll.c:

#include <windows.h>

int WINAPI
mydll_init(HANDLE h, DWORD reason, void *foo)
{
  return 1;
}

First compile mydll.c to object code:

gcc -c mydll.c

Then, tell gcc that it is building a shared library:

gcc -shared -o mydll.dll mydll.o

That's it! However, if you are building a dll as an export library,
you will probably want to use the complete syntax:

gcc -shared -o cyg${module}.dll \
    -Wl,--out-implib=lib${module}.dll.a \
    -Wl,--export-all-symbols \
    -Wl,--enable-auto-import \
    -Wl,--whole-archive ${old_lib} \
    -Wl,--no-whole-archive ${dependency_libs}

Where ${module} is the name of your DLL, ${old_lib} are all
your object files, bundled together in static libs or single object
files and the ${dependency_libs} are import libs you need to
link against, e.g '-lpng -lz -L/usr/local/special -lmyspeciallib'

--------End new text--------


--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Soren A]

Joshua Daniel Franklin <joshua@iocc.com> wrote around 20 Aug 2002 
news:Pine.CYG.4.44.0208202127280.1336-100000@joshua.iocc.com about %s:

> Here is some new text to replace the section at
> 
> http://cygwin.com/cygwin-ug-net/dll.html
> 
> that begins with "Unfortunately, the process for building a dll is, well,
> convoluted. You have to run five commands, like this"

I am making my own local copy of the document right now. Could you confirm 
for me at what point your replacement section _ends_, please? Is it at the 
next major section heading, "Linking Against DLLs"? I am not confidently 
familiar enough with the material to know that the whole section between 
the two points can be jettisoned.

  Thanks!!!
    Soren A





--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Soren A]

Joshua Daniel Franklin <joshua@iocc.com> wrote around 20 Aug 2002 
news:Pine.CYG.4.44.0208202127280.1336-100000@joshua.iocc.com about %s:

> Thanks for the update on dll-building. I almost missed this one...
> I was thinking "Why doesn't someone just update the documentation?"

BTW, in another vein, but also regarding the Cygwin UG there's a small
detail: there seems to be a stylesheet gone missing from the pages. The
markup on the pages reference CSS classes that aren't defined and
clearly are supposed to come from an external stylesheet that's declared
somewhere in each HTML page's headers? Does the document maintainer know
about this? 

TIA,
  Soren A



--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Gerrit P. Haase]

Hallo Joshua,

Am Mittwoch, 21. August 2002 um 04:28 schriebst du:

> Gerrit and other dll-builders,

> Thanks for the update on dll-building. I almost missed this one...
> I was thinking "Why doesn't someone just update the documentation?"
> then realized "Hey, I volunteered to do that, didn't I?"
> (BTW, everyone--could I get heads-up about the User's Guide like David gets
> about the FAQ?)

> Here is some new text to replace the section at

> http://cygwin.com/cygwin-ug-net/dll.html

> that begins with "Unfortunately, the process for building a dll is, well,
> convoluted. You have to run five commands, like this"
> This is not the actual patch, I will submit one of those after
> I verify that I've got the subject matter correct.
> Please read carefully since I'm not an expert in this area and may have
> mixed up some terminology or concepts.

> --------Begin new text--------

Maybe it would be easier to get into with a real example
(s.th. like this, without your comments):

dlltest.C:
==========
#include<iostream>
int
hello ()
{
  using namespace std;
  cout << "Just another dll hacker,";
}

$ g++ -c dlltest.C

$ g++ -shared -o mydll.dll \
> -Wl,--out-implib=libmydll.dll.a \
> -Wl,--export-all-symbols \
> -Wl,--enable-auto-import \
> -Wl,--whole-archive dlltest.o \
> -Wl,--no-whole-archive


exetest.C:
==========
void hello ();

int
main ()
{
  hello ();
  return 1;
}

$ g++ -o exetest exetest.C -L/d/dlltest -lmydll

$ ./exetest
Just another dll hacker,


> Fortunately, with the latest gcc and binutils the process for building a dll
> is now much simpler. Say you want to build this minimal function in mydll.c:

> #include <windows.h>

> int WINAPI
> mydll_init(HANDLE h, DWORD reason, void *foo)
> {
>   return 1;
> }

> First compile mydll.c to object code:

> gcc -c mydll.c

> Then, tell gcc that it is building a shared library:

> gcc -shared -o mydll.dll mydll.o

> That's it! However, if you are building a dll as an export library,
> you will probably want to use the complete syntax:

> gcc -shared -o cyg${module}.dll \
>     -Wl,--out-implib=lib${module}.dll.a \
>     -Wl,--export-all-symbols \
>     -Wl,--enable-auto-import \
>     -Wl,--whole-archive ${old_lib} \
>     -Wl,--no-whole-archive ${dependency_libs}

> Where ${module} is the name of your DLL, ${old_lib} are all
> your object files, bundled together in static libs or single object
> files and the ${dependency_libs} are import libs you need to
> link against, e.g '-lpng -lz -L/usr/local/special -lmyspeciallib'

> --------End new text--------



-- 
=^..^=


--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Wed, Aug 21, 2002 at 03:21:20PM +0000, Soren A wrote:
>Joshua Daniel Franklin <joshua@iocc.com> wrote around 20 Aug 2002 
>news:Pine.CYG.4.44.0208202127280.1336-100000@joshua.iocc.com about %s:
>
>> Thanks for the update on dll-building. I almost missed this one...
>> I was thinking "Why doesn't someone just update the documentation?"
>
>BTW, in another vein, but also regarding the Cygwin UG there's a small
>detail: there seems to be a stylesheet gone missing from the pages. The
>markup on the pages reference CSS classes that aren't defined and
>clearly are supposed to come from an external stylesheet that's declared
>somewhere in each HTML page's headers? Does the document maintainer know
>about this? 

As is so often the case, the document maintainer would be fascinated by
details.

cgf

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Soren A]

Christopher Faylor <cgf@redhat.com> wrote around 21 Aug 2002 
news:20020821154045.GB21737@redhat.com about %s:

> As is so often the case, the document maintainer would be fascinated
> by details.

And in this case, the document maintainer (which i presume you are
implying is you yourself?) gets to be told, as he has told so many
others: "look at some code, what's wrong with you, don't you run a text
editor?" ;-) 

There's really no more details to give than that stated in my previous
message. There's no external CSS stylesheet referenced on the Cygwin UG
pages. OK, want code? here's the header for one such page* as it is
presented to my User Agent: 

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
  <HTML
  ><HEAD
  ><TITLE
  >Expectations for UNIX Programmers</TITLE
  ><META
  NAME="GENERATOR"
  CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  "><LINK
  REL="HOME"
  TITLE="Cygwin User's Guide"
  HREF="cygwin-ug-net.html"><LINK
  REL="UP"
  TITLE="Cygwin Overview"
  HREF="overview.html"><LINK
  REL="PREVIOUS"
  TITLE="A brief history of the Cygwin project"
  HREF="brief-history.html"><LINK
  REL="NEXT"
  TITLE="Expectations for Windows Programmers"
  HREF="ov-ex-win.html"></HEAD
  >

* http://cygwin.com/cygwin-ug-net/ov-ex-unix.html

(Indentation done to emphasize that this is a pasted-in block of text. The 
malformed line breaks before the closing '>' of tags are NOT an artifact of 
my email agent or copy-and-paste procedure but are literally there in the 
Cygwin server docs as they are served to my User Agent.)

There are a couple standard mechanisms for including CSS stylesheets into 
the HTML document. None seem to be in use here. The documentation seems to 
be auto-generated by 'DocBook' which is something I know nothing about; I 
suspect that this is where some answers lie, though.

   HTH,
    Soren A



--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Wed, Aug 21, 2002 at 03:52:44PM +0000, Soren A wrote:
>gets to be told, as he has told so many others: "look at some code,
>what's wrong with you, don't you run a text editor?" ;-)

Not the same thing.  It's the standard bug reporting technique of
assuming that the people reading the mail are mind readers who are
clued into exact knowledge of a problem.

If you have a specific suggestion, I'd like to hear it.

I should make it clear that I know nothing about stylesheets.  As you
noted, this is autogenerated code.  If you see a specific problem with
it then a specific suggestion is appropriate.

cgf

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Tue, Aug 20, 2002 at 09:28:22PM -0500, Joshua Daniel Franklin wrote:
>Here is some new text to replace the section at
>
>http://cygwin.com/cygwin-ug-net/dll.html

I've checked this new description into CVS and regenerated the web
pages.  It's certainly better than what was there before even if it
does conceivably need some tweaking.

cgf

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Wed, Aug 21, 2002 at 12:56:36PM -0400, Christopher Faylor wrote:
>On Tue, Aug 20, 2002 at 09:28:22PM -0500, Joshua Daniel Franklin wrote:
>>Here is some new text to replace the section at
>>
>>http://cygwin.com/cygwin-ug-net/dll.html
>
>I've checked this new description into CVS and regenerated the web
>pages.  It's certainly better than what was there before even if it
>does conceivably need some tweaking.

Btw, some words indicating that it is possible to link directly against
the dll itself rather than generating a def file, would be nice in the
linking section.

cgf

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Soren A]

Christopher Faylor <cgf@redhat.com> wrote around 21 Aug 2002
news:20020821162436.GE21737@redhat.com about %s: 

> Not the same thing.  It's the standard bug reporting technique of
> assuming that the people reading the mail are mind readers who are
> clued into exact knowledge of a problem.

Not really, Chris. In this case, the reality is not that there was
anything inadaquate about my report/query, but rather the inadaquacy is
entirely on your part. You are the documentation maintainer and yet you
know nothing about aspects of the tools you use? HEY. 

> If you have a specific suggestion, I'd like to hear it.

It's really not a major issue. Users can write their own stylesheets,
and on a User Agent like Opera (and prob. Mozilla) they can configure
their UA to use them. The absence of the stylesheets (which REALLY
aren't that mysterious, Chris; they are by analogy just like a C header
but not a fatal error if they are missing...) doesn't impact the
documents in such a way as to render them unusable (which is precisely
the basic principle behind css to begin with). 

> I should make it clear that I know nothing about stylesheets.  As you
> noted, this is autogenerated code.  If you see a specific problem with
> it then a specific suggestion is appropriate.

Yes. My specific suggestion is that you learn your tools. It is not
farfetched to suppose that somewhere in the user documentation that
exists for DocBook there is info pertaining to generation and
configuration of stylesheets to complement the application's HTML
output. 

  Regards,
    Soren A




--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Wed, Aug 21, 2002 at 05:36:56PM +0000, Soren A wrote:
>Christopher Faylor <cgf@redhat.com> wrote around 21 Aug 2002
>news:20020821162436.GE21737@redhat.com about %s: 
>
>> Not the same thing.  It's the standard bug reporting technique of
>> assuming that the people reading the mail are mind readers who are
>> clued into exact knowledge of a problem.
>
>Not really, Chris. In this case, the reality is not that there was
>anything inadaquate about my report/query, but rather the inadaquacy is
>entirely on your part. You are the documentation maintainer and yet you
>know nothing about aspects of the tools you use? HEY. 

Although I admitted to ignorance (I try to do that when I'm not up to
speed on something), you are assuming that I should apply expert status
to *you*.  You are assuming that I should take your notice of "something
wrong" as having some weight when there is, so far, no evidence that I
should do so.

Actually, ignorance is probably too strong a term for my state.  I
suppose I am now a "newbie" when it comes to style sheets.  I did scan
the appropriate documentation about style sheets and then inspected the
cygwin html.  I did that prior to sending my first message.  I don't see
anything wrong with the user guide html.  I'm willing to be proven
wrong, however, with specific examples, which you are, so far, unwilling
to provide.

I suppose it is possible that you are referring to the use of the words
"StyleSheet" in the meta tag at the top of the generated code.  AFAIK,
meta tags do not have anything to do with style sheets, and the mention
of a style sheet in this context is merely to illustrate that the
DocBook HTML stylesheet was used to generate the html.  However, if you
have more information on this, then it would certainly be welcome.
Hmm.  Starting to repeat myself.

So, basically, in absence of any specifics, I'll just take your reported
problems as indicating erroroneous assumptions on your part.  Feel free
to taunt me about not knowing how to use my tools some more if it makes
you feel better.  Either that or provide specific information.

cgf

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Robert Collins]

[-- Attachment #1: Type: text/plain, Size: 1589 bytes --]

On Thu, 2002-08-22 at 04:57, Christopher Faylor wrote:

> I suppose it is possible that you are referring to the use of the words
> "StyleSheet" in the meta tag at the top of the generated code.  AFAIK,
> meta tags do not have anything to do with style sheets, and the mention
> of a style sheet in this context is merely to illustrate that the
> DocBook HTML stylesheet was used to generate the html.  However, if you
> have more information on this, then it would certainly be welcome.
> Hmm.  Starting to repeat myself.
> 
> So, basically, in absence of any specifics, I'll just take your reported
> problems as indicating erroroneous assumptions on your part.  Feel free
> to taunt me about not knowing how to use my tools some more if it makes
> you feel better.  Either that or provide specific information.

Nyahh nyah nya-nyah nyah. Taunted yet?

Hope I'm not interfering my jumping in the middle of this mounting...
conversation.

For the archive (as the FAQ reference may not be obvious to future
searchers):

Docbook generated HTML tags the HTML tags with similar classes to those
used in the SGML source to allow _optional_ overriding of the format on
a per-class basis. (For instance <H1 class="Title">. Here the class is
title, and if wanted the title larger we could include an inline style
sheet, or a reference to an includeable style sheet in a META tag in the
HEAD). 

Soren's reference to a 'missing' style sheet is because there is no
style sheet specified, but we use all these styles.

Soren: This is fine, it's by design.

Rob


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Thu, Aug 22, 2002 at 09:01:37AM +1000, Robert Collins wrote:
>For the archive (as the FAQ reference may not be obvious to future
>searchers):
>
>Docbook generated HTML tags the HTML tags with similar classes to those
>used in the SGML source to allow _optional_ overriding of the format on
>a per-class basis. (For instance <H1 class="Title">. Here the class is
>title, and if wanted the title larger we could include an inline style
>sheet, or a reference to an includeable style sheet in a META tag in the
>HEAD). 
>
>Soren's reference to a 'missing' style sheet is because there is no
>style sheet specified, but we use all these styles.
>
>Soren: This is fine, it's by design.

Thanks for the clarification.  I'll be happy if I don't have to
understand the Docbook stuff.  HAs I've previously mentioned, I think it
may actually be a barrier to entry to working on the docs.  My Docbook
installation seems to break after each OS upgrade.  Maybe that explains
the strangely formatted html.

cgf

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Robert Collins]

[-- Attachment #1: Type: text/plain, Size: 702 bytes --]

On Fri, 2002-08-23 at 12:34, Christopher Faylor wrote:

> Thanks for the clarification.  I'll be happy if I don't have to
> understand the Docbook stuff.  As I've previously mentioned, I think it
> may actually be a barrier to entry to working on the docs.  My Docbook
> installation seems to break after each OS upgrade.  Maybe that explains
> the strangely formatted html.

Likewise, as I've offered before, I'm happy to assist on docbook
problems (related to Cygwin, naturally). Docbook is in *very* wide use,
and there are plenty of resources for contributors to read to get up to
speed. I don't think it's any more of a barrier to entry than
understanding C or C++.

Cheers,
Rob


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Updating dll info in the User's Guide

[Nicholas Wourms]

--- Robert Collins <rbcollins@cygwin.com> wrote:
> On Fri, 2002-08-23 at 12:34, Christopher Faylor wrote:
> 
> > Thanks for the clarification.  I'll be happy if I don't have to
> > understand the Docbook stuff.  As I've previously mentioned, I
> think it
> > may actually be a barrier to entry to working on the docs.  My
> Docbook
> > installation seems to break after each OS upgrade.  Maybe that
> explains
> > the strangely formatted html.
> 
> Likewise, as I've offered before, I'm happy to assist on docbook
> problems (related to Cygwin, naturally). Docbook is in *very* wide
> use,
> and there are plenty of resources for contributors to read to get
> up to
> speed. I don't think it's any more of a barrier to entry than
> understanding C or C++.

Well I think the lack of a decent docbook installation for cygwin is
a *big* barrier.  Docbook is such a PITA to setup that I detest every
second of it.  I mean we're talking about the type of setup
reminiscent of Redhat 3.0.3, where things got installed, but it was a
considierable timesink just to get the $%#^ing stuff to work right. 
Even then it seems to work by voodoo, and I always forget what I did
to make it work (lots of trial and error).  A small rant, but I
*really* *really* *really* wish the various docbook maintainers would
get on the same page and establish a freakin' standard as to how the
docbook directory structure should be layed out.  I fear the would-be
docbook maintainer, Jon, has become a victim of his skydiving hobby.
Either that, or he's just ignoring my e-mails =).  Oh well, hopefully
someone will step up to the plate.

Cheers,
Nicholas

__________________________________________________
Do You Yahoo!?
Yahoo! Finance - Get real-time stock quotes
http://finance.yahoo.com

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Updating dll info in the User's Guide

[Joshua Daniel Franklin]

References: <Pine.CYG.4.44.0208202127280.1336-100000@joshua.iocc.com>
<Xns927173B917AEDsoren1Gmane@80.91.224.249> <20020821154045.GB21737@redhat.com>
<Xns9271790BEA4BDsoren1Gmane@80.91.224.249> <20020821162436.GE21737@redhat.com>
<Xns92718AB657BD2soren1Gmane@80.91.224.249>

"Soren A" <soren_andersen@fastmail.fm> wrote:
>
> There are a couple standard mechanisms for including CSS stylesheets into
> the HTML document. None seem to be in use here. The documentation seems to
> be auto-generated by 'DocBook' which is something I know nothing about; I
> suspect that this is where some answers lie, though.

DocBook FAQ:

http://www.dpawson.co.uk/docbook/

> > I should make it clear that I know nothing about stylesheets.  As you
> > noted, this is autogenerated code.  If you see a specific problem with
> > it then a specific suggestion is appropriate.
>
> Yes. My specific suggestion is that you learn your tools. It is not
> farfetched to suppose that somewhere in the user documentation that
> exists for DocBook there is info pertaining to generation and
> configuration of stylesheets to complement the application's HTML
> output.

I believe I'm actually the one who's supposed to be working on improving
the documentation. I have noticed that the HTML produced could be better
(especially that putting the ">" on the next line issue), but I don't (yet?)
know how to make it better. 

What I do know is that right now the HTML User's Guide looks decent in most
every browser, and I have heard about stylesheets that
Netscape 4.x does not support them very well. So I echo Chris':

> > If you have a specific suggestion, I'd like to hear it.

__________________________________________________
Do You Yahoo!?
HotJobs - Search Thousands of New Jobs
http://www.hotjobs.com

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/