Mail Archives: cygwin/2002/03/03/00:17:07
--------------080409090707050007030805
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit
Michael Schaap wrote:
> (Chuck, if you think this would be a good addition for cygutils, feel
> free to include it! After all, I did "borrow" some of the code
> framework from it. :-) )
Hmmm...how does this differ from the "run" utility here:
http://www.neuro.gatech.edu/users/cwilson/cygutils/unversioned/run/
It may be entirely different; I'm not sure. Certainly they were written
for different purposes. Run was intended to hide the console for GUI
programs that still expect a stdout/stderr console.
Run doesn't use popt :-( so it doesn't have pretty help, but it can be
compiled as a native windows app :-)
Anyway, I personally have no objection to including start in cygutils --
but the sudden appearance of a 'start.exe' command in /usr/bin (which
could hide WINNT/start.exe) may cause consternation in some quarters.
FYI, I've just completed the following HOW-TO-CONTRIBUTE (to cygutils)
document. It will show up in /usr/doc/cygutils-X.Y.Z/ in the next
release of cygutils.
--Chuck
--------------080409090707050007030805
Content-Type: text/plain;
name="HOW-TO-CONTRIBUTE"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="HOW-TO-CONTRIBUTE"
So, you have a utility that you believe would
be a good addition to cygutils, do you? You
probably want to know how you could contribute it,
don't you? Well, first:
Don't just send me yourfile.c and expect me to
do all the integration work.
You need to do more than merely insure that it builds
on your machine with a simple
gcc -o yourfile.exe yourfile.c -lthislibrary -lthatlibrary
In addition to that, you need to check out the cygutils
source and integrate yourfile into the whole system. Instructions
follow below. However, you'll notice that it's quite a bit
of work. You may want to send an exploratory email to
cygwin AT cygwin DOT com and explain your programs behavior, what
need it fills, and get pre-clearance for eventual inclusion
into cygutils before embarking on the journey outlined below.
Also, note that I will not fix your bugs. If, at some time
after your program is accepted into cygutils, I (as cygutils
maintainer) get a bug report on your program, I will forward
it to you. If you don't fix it or respond within a reasonable
time, I will remove it from the distribution.
------------------------------------------------------
Okay, now that we're past that unpleasantness, here's how to
integrate your spiffy new utility. First, let's assume that
your spiffy utility is called 'foo', and its source is in 'foo.c'.
The simple 12 step program:
---------------------------
1) Get the cygutils source
cvs -d:pserver:anoncvs AT sources DOT redhat DOT com:/cvs/cygwin-apps login
use 'anoncvs' as the password
cvs -z3 -d:pserver:anoncvs AT sources DOT redhat DOT com:/cvs/cygwin-apps co cygutils
you now have a 'cygutils' directory with the existing source.
2) License information
make sure that all .c and .h files in your contribution
have license information: preferably GPL, but other
open licenses are acceptable, too. See the top of
src/lpr/lpr.c for an example.
a) if your license is not GPL or BSD-no-advert, then
you must also include a copy of the ENTIRE license
in the licenses subdirectory. (Most of the time,
the blurb in the .c or .h file is just that: a short
blurb, with a reference to the full text elsewhere)
3) Make a home
create a new directory for your contribution underneath 'src'
In our case, we will do this:
cd cygutils/src
mkdir foo
copy your source into the new directory
cp <location>/foo.c <cygutils>/src/foo/
4) Modify your source code
Add the following snippet to the beginning of your .c and .h(*)
files, just after the license information:
#if HAVE_CONFIG_H
#include "config.h"
#endif
#include "common.h"
a) If your contribution has its own .h file(s), the entire .h file
should be "guarded" as follows:
/* license information */
#ifndef _FOO_H
#define _FOO_H
/* the config.h/common.h stuff */
/* your header stuff */
#endif /* !_FOO_H */
the "_FOO_H" identifier should be changed to match the filename
of your header file. Thus, "bob.h" would be guarded with _BOB_H.
5) Makefile.am
Create a Makefile.am file in your 'foo' directory. If your
contribution will build on non-windows platforms in addition to
cygwin, then Makefile.am should look like this:
## Makefile.am -- Process this file with automake to produce Makefile.in
INCLUDES = -I$(top_builddir) -I$(top_srcdir)
bin_PROGRAMS = foo
## end
(Yes, really. That's it). If your contribution is windows-specific,
like lpr or mkshortcut or the [put|get]clip programs, then your
Makefile.am should look like:
## Makefile.am -- Process this file with automake to produce Makefile.in
INCLUDES = -I$(top_builddir) -I$(top_srcdir)
if WITH_WINDOWS_PROGRAMS
windows_progs = foo
endif
bin_PROGRAMS = $(windows_progs)
EXTRA_PROGRAMS = foo
## end
a) Special link libraries
If you need to link to special *WINDOWS* libraries, then obviously
your program is windows-specific, but also you should add a line
in your Makefile.am like this:
foo_LDADD = -lwinlib
Where foo is your program name, and winlib is the library you need.
See src/lpr/Makefile.am or src/mkshortcut/Makefile.am for
more examples.
If, on the other hand, you need to link to some other (cygwin)
library that is also more generally available -- like libreadline
or libncurses -- then you'll need to do a little more work.
For your initial submission, just add the -lreadline (or whatever)
command to your Makefile.am foo_LDADD line. However, make sure
to let me know about your special link requirements.
Note that you do NOT need to include the following libraries in
a 'foo_LDADD' line; these will be added automatically...
-lintl -lcygipc -lpopt (that is, gettext, cygipc, or popt)
b) man pages and other documentation
If you got 'em, copy 'em to your foo directory, and add a line
to your Makefile.am like this:
man_MANS = foo.1
If there are non-man-page documentation files, you should add
a line like this:
EXTRA_DIST = foo.README
However, there is no provisiion for actually INSTALLING these
additional documentation files. At least not yet.
c) Extra files
If your contribution consists of more source files than a single
.c, then you need to add a line that lists all of them in your
Makefile.am:
foo_SOURCES = foo.c otherfoo.c foo.h
If there are .h files in that list, you should also add a line
like this:
noinst_HEADERS = foo.h
If you have other questions about the Makefile.am file, consult
the other ones already in cygutils as examples, or read the
automake documentation.
6) Simplify your #includes.
Take a good look at the #include statements in your .c and .h
files. If the dependencies are listed in <cygutils>/common.h,
then you shouldn't re-include them. If a dependency is NOT
listed in common.h, then leave it in your .h/.c file -- for
now. We may choose to add them to common.h and add new tests
to configure.ac, or we may choose to let your .c file
include it directly. However, anything that's already in
common.h, remove from your .c/.h file. It's okay to just
comment them out, rather than deleting them entirely, if
you prefer.
7) Add information to cygutils documentation files:
Add a short blurb about your app to <cygutils>/PROGLIST
Add your app to the list at the end of the README file
Add your name to the AUTHORS file.
8) Hook your directory into the package build structure
Add the name of your directory in src to the list in
src/Makefile.am.
Add your Makefile to the list at the end of configure.ac
9) Bootstrap
(You need to have autoconf, autoconf-devel, automake, and
automake-devel installed for this to work). Change dir
to the top of your checked-out source, and run bootstrap:
cd <cygutils>
./bootstrap
If you haven't made any mistakes, you should (a) see no
errors, and (b) see a Makefile.in file added to your foo
directory.
10) Build and test
Now, just run './configure ; make' as usual. Somewhere
amongst the flurry of messages, you should see your application
being built. If so, you're almost done. If not, then you
need to figure out why. Time to read the auto* documentation...
11) Create a patch and ChangeLog entry
a) PATCH
cd <cygutils>
cvs diff -u > foo.patch
If you've already edited the ChangeLog file, make sure to
*remove* that chunk from foo.patch. I don't want a PATCH
for the ChangeLog, I want the ChangeLog entry itself (ChangeLog
patches rarely apply cleanly; it's easier to cut-n-paste. More
below).
b) NEW FILES
However, you'll notice that none of the files in your src/foo
directory are represented in the patch. That's normal. Remove
any .o and .exe files from src/foo, and then just make a tarball
cd <cygutils>
tar cvjf foo.tar.bz2 src/foo
c) CHANGELOG
You should also create a ChangeLog entry. Don't actually edit
the ChangeLog itself; create a new file (foo.changelog?) and
put your stuff there. It should look like this:
2002-03-02 Your Name <your_email_address AT domain DOT com>
* src/foo: new directory
* src/foo/Makefile.am: new file
* src/foo/Makefile.in: new file
* src/foo/foo.c: new file
* src/Makefile.am: add subdirectory foo
* src/Makefile.in: regenerate
* configure.ac: add src/foo/Makefile to output list
* AUTHORS: add yourname for foo
* PROGLIST: add foo
* README: add foo
Don't list src/foo/Makefile. Do list every original
file in src/foo/ (like your man pages, or extra documentation
files, or headers)
12) Send an email to cygwin AT cygwin DOT com with the patch and the
tarball as attachements. Paste your changelog into the body
of the message -- or you can send it as an attachment. (Do NOT
put your patch into the body of the email; most mail programs
will horrendously distort it if you do).
In the body of your email, Describe what your program does, why
it's needed, and why you think it should be added to the
cygutils package. Also explain why (or state that) existing
tools will not meet the need your program does. Also, be
sure and warn of any special link requirements (cf. section
5a and 5b above).
--
Chuck Wilson
cygutils maintainer
--------------080409090707050007030805
Content-Type: text/plain; charset=us-ascii
--
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/
--------------080409090707050007030805--
- Raw text -