probably want to know how you could contribute it,
don't you? Well, first:
+ Not every spiffy utility belongs in cygutils. We
+ don't want cygutils to become a huge grab bag of
+ hundreds of small programs...in many cases, your
+ spiffy new program should become a standalone package
+ and a full-fledged member of the cygwin distribution.
+ (Don't worry -- that's not hard. It's probably
+ easier than integrating your spiffy program into
+ cygutils).
+
+ So, your first step is to post a message to the
+ cygwin-apps mailing list, present your program, and
+ ASK if it should be included in cygutils, or turned
+ into a standalong package. If you believe it should
+ become part of cygutils, explain why. I will not
+ add any program to cygutils without a consensus
+ from the cygwin-apps list.
+
+ 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.
+
+Second, once you're obtained agreement that yourfile.c
+should be added to cygutils:
+
Don't just send me yourfile.c and expect me to
do all the integration work.
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@cygwin.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.
+of work. Again, are you SURE you want it to become part
+of cygutils? Making a standalone program is a lot easier...
+
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
the blurb in the .c or .h file is just that: a short
blurb, with a reference to the full text elsewhere)
+ You should also add it to the licenses variable in
+ the toplevel Makefile.am: e.g.
+
+ licenses = ... licenses/COPYING.MPL ...
+
3) Make a home
create a new directory for your contribution underneath 'src'
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
+ Naturally, the header files should also be copied into src/foo/.
- 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:
+5) Modify cygutils/Makefile.am
- ## Makefile.am -- Process this file with automake to produce Makefile.in
- INCLUDES = -I$(top_builddir) -I$(top_srcdir)
- bin_PROGRAMS = foo
- ## end
+ a) Add your program to the list of progs to be built. If your
+ program will build on non-windows platforms in addition to cygwin,
+ then you can add your program to the "bin_PROGRAMS" variable:
- (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:
+ bin_PROGRAMS = ... src/foo/foo ...
- ## 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
+ If your contribution is windows-specific, then you should add it
+ to BOTH the "windows_progs" and the EXTRA_PROGRAMS variables:
- a) Special link libraries
+ windows_progs = ... src/foo/foo ...
+ EXTRA_PROGRAMS = ... src/foo/foo ...
+
+ b) 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:
+ 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:
+
+ src_foo_foo_LDADD = -lwinlib
+
+ Where "src_foo_foo" is the path to your program, where the '/'
+ characters are replaced with '_' characters. Yes, it looks a little
+ funny -- but because our subdirectory has the same name as our
+ program, we get double foo's... Also, 'winlib' is the library
+ that you need. See the src_lpr_lpr_LDADD variable in Makefile.am
+ for an example.
+
+ 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 create an LDADD variable in
+ Makefile.am with -lreadline (or whatever). We'll figure out how
+ to handle it better further down the road. However, make sure
+ to let me know about your special link requirements.
- foo_LDADD = -lwinlib
+ src_foo_foo_LDADD = -lreadline
- 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.
+ One special case is the gettext internationalization libraries.
+ If your program must link with -lintl, then all you need to
+ do is create an LDADD variable as follows:
- 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.
+ src_foo_foo_LDADD = @LIBINTL@
- Note that you do NOT need to include the following libraries in
- a 'foo_LDADD' line; these will be added automatically...
+ The configuration process will replace @LIBINTL@ with the
+ appropriate -lintl -liconv invocation.
- -lintl -lcygipc -lpopt (that is, gettext, cygipc, or popt)
+ Note that you do NOT need to include the popt library in
+ a 'src_foo_foo_LDADD' line; -lpopt will be added automatically...
- b) man pages and other documentation
+ If your app depends on IPC functions, then add @IPCLIBS@
+ to the 'src_foo_foo_LDADD' line.
- If you got 'em, copy 'em to your foo directory, and add a line
- to your Makefile.am like this:
+ c) man pages and other documentation
- man_MANS = foo.1
+ If you got 'em, copy 'em to your src/foo directory, and add the
+ manpage to the man_MANS variable in Makefile.am like this:
- If there are non-man-page documentation files, you should add
- a line like this:
+ man_MANS = ... src/foo/foo.1 ...
- EXTRA_DIST = foo.README
+ If there are non-man-page documentation files, you should do
+ one of the following:
+ i) if your app is windows-specific, then create a new
+ variable inside the 'if WITH_WINDOWS_PROGRAMS' section
+ suffixed with '_docs', and list the documentation files
+ foo_docs = src/foo/README src/foo/TODO
+ Also, add those files to the extra_docs variable (which
+ gets automatically included in EXTRA_DIST)
+ extra_docs = src/foo/README src/foo/TODO
+ ii) otherwise, simply create the 'foo_docs' variable
+ outside of the 'if WITH_WINDOWS_PROGRAMS' section
+ These files will be installed into $(docdir)/foo/ so there
+ is no worry that your README will conflict with any other
+ component's README.
- However, there is no provisiion for actually INSTALLING these
- additional documentation files. At least not yet.
+ d) Extra files
- c) Extra files
+ If your contribution consists of more source files than a single
+ .c, then you need to add a variable to Makefile.am that lists all
+ of them:
- 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:
+ src_foo_foo_SOURCES = foo.c otherfoo.c foo.h
- foo_SOURCES = foo.c otherfoo.c foo.h
+ Note that this variable should NOT be specified if your program
+ consists merely of a single .c file whose name is the same as
+ your program + '.c'.
- If there are .h files in that list, you should also add a line
- like this:
+ If there are .h files in your SOURCES list, then you need to
+ add those .h files to the noinst_HEADERS variable, or the headers
+ would get installed into /usr/include/src/foo/ -- and we don't
+ want that!
- noinst_HEADERS = foo.h
+ noinst_HEADERS = ... src/foo/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.
+ If you have other questions about the Makefile.am file, try to
+ follow the "patterns" established in it by the other programs,
+ or (gasp) read the automake documentation.
+
+ Libraries are quite complicated to deal with in the cygutils
+ build framework. Fortunately I doubt there will be many of
+ these to worry about, other than cygicons.
6) Simplify your #includes.
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
+ Add your name to the AUTHORS file. Don't worry about NEWS;
+ I do that before each release.
-9) Bootstrap
+8) Bootstrap
(You need to have autoconf, autoconf-devel, automake, and
automake-devel installed for this to work). Change dir
./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.
+ errors, and (b) see some new rules in Makefile.in that
+ correspond to your program.
-10) Build and test
+9) 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
+10) Create a patch and ChangeLog entry
a) PATCH
2002-03-02 Your Name <your_email_address@domain.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
+ * Makefile.am: add program 'foo'
+ * Makefile.in: regenerate
* AUTHORS: add yourname for foo
* PROGLIST: add foo
* README: add foo
file in src/foo/ (like your man pages, or extra documentation
files, or headers)
-12) Send an email to cygwin@cygwin.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).
+11) Send a notice email to cygwin-apps@cygwin.com, that says "Hey, I
+ finished the integration work neceesary to include 'foo' in the
+ 'cygutils' package, as previously agreed on this list." Paste
+ the ChangeLog into that notice. But do NOT send the patch or
+ tarball to the mailing list.
- 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).
+ Instead, send that to ME, cygwin@cwilson.fastmail.fm. The patch
+ and tarball should be attachments, but paste the ChangeLog entry
+ into the body of the message. Do NOT paste your patch into the
+ body of the email; most mail programs will horrendously distort
+ it if you do). Also, be sure and warn of any special link
+ requirements (cf. section 5a and 5b above).
+
+12) Bask in the glow of a job well done.
--
Chuck Wilson
cygutils maintainer
+
+Note to self: how to commit contributions:
+ apply the patch
+ untar the contribution
+ Add the Changelog entry
+ ./bootstrap
+ cvs add src/directory
+ cvs add src/directory/srcfiles
+ cvs commit -m "Add foo contribution"
+ ./bootstrap
+ cvs diff | grep Index > foo
+ >>> use 'foo' to add another Changelog entry
+ cvs commit -m "Add foo contribution"
+ cvs tag something
+
git://cygwin.com / cygwin-apps / cygutils.git / blobdiff