1 So, you have a utility that you believe would
2 be a good addition to cygutils, do you? You
3 probably want to know how you could contribute it,
4 don't you? Well, first:
6 Not every spiffy utility belongs in cygutils. We
7 don't want cygutils to become a huge grab bag of
8 hundreds of small programs...in many cases, your
9 spiffy new program should become a standalone package
10 and a full-fledged member of the cygwin distribution.
11 (Don't worry -- that's not hard. It's probably
12 easier than integrating your spiffy program into
15 So, your first step is to post a message to the
16 cygwin-apps mailing list, present your program, and
17 ASK if it should be included in cygutils, or turned
18 into a standalong package. If you believe it should
19 become part of cygutils, explain why. I will not
20 add any program to cygutils without a consensus
21 from the cygwin-apps list.
23 In the body of your email, describe what your program
24 does, why it's needed, and why you think it should be
25 added to the cygutils package. Also explain why (or
26 state that) existing tools will not meet the need your
29 Second, once you're obtained agreement that yourfile.c
30 should be added to cygutils:
32 Don't just send me yourfile.c and expect me to
33 do all the integration work.
35 You need to do more than merely insure that it builds
36 on your machine with a simple
38 gcc -o yourfile.exe yourfile.c -lthislibrary -lthatlibrary
40 In addition to that, you need to check out the cygutils
41 source and integrate yourfile into the whole system. Instructions
42 follow below. However, you'll notice that it's quite a bit
43 of work. Again, are you SURE you want it to become part
44 of cygutils? Making a standalone program is a lot easier...
46 Also, note that I will not fix your bugs. If, at some time
47 after your program is accepted into cygutils, I (as cygutils
48 maintainer) get a bug report on your program, I will forward
49 it to you. If you don't fix it or respond within a reasonable
50 time, I will remove it from the distribution.
52 ------------------------------------------------------
54 Okay, now that we're past that unpleasantness, here's how to
55 integrate your spiffy new utility. First, let's assume that
56 your spiffy utility is called 'foo', and its source is in 'foo.c'.
58 The simple 12 step program:
59 ---------------------------
61 1) Get the cygutils source
63 cvs -d:pserver:anoncvs@sources.redhat.com:/cvs/cygwin-apps login
64 use 'anoncvs' as the password
65 cvs -z3 -d:pserver:anoncvs@sources.redhat.com:/cvs/cygwin-apps co cygutils
67 you now have a 'cygutils' directory with the existing source.
69 2) License information
71 make sure that all .c and .h files in your contribution
72 have license information: preferably GPL, but other
73 open licenses are acceptable, too. See the top of
74 src/lpr/lpr.c for an example.
76 a) if your license is not GPL or BSD-no-advert, then
77 you must also include a copy of the ENTIRE license
78 in the licenses subdirectory. (Most of the time,
79 the blurb in the .c or .h file is just that: a short
80 blurb, with a reference to the full text elsewhere)
82 You should also add it to the licenses variable in
83 the toplevel Makefile.am: e.g.
85 licenses = ... licenses/COPYING.MPL ...
89 create a new directory for your contribution underneath 'src'
90 In our case, we will do this:
94 copy your source into the new directory
95 cp <location>/foo.c <cygutils>/src/foo/
97 4) Modify your source code
99 Add the following snippet to the beginning of your .c and .h(*)
100 files, just after the license information:
107 a) If your contribution has its own .h file(s), the entire .h file
108 should be "guarded" as follows:
110 /* license information */
113 /* the config.h/common.h stuff */
114 /* your header stuff */
117 the "_FOO_H" identifier should be changed to match the filename
118 of your header file. Thus, "bob.h" would be guarded with _BOB_H.
120 Naturally, the header files should also be copied into src/foo/.
122 5) Modify cygutils/Makefile.am
124 a) Add your program to the list of progs to be built. If your
125 program will build on non-windows platforms in addition to cygwin,
126 then you can add your program to the "bin_PROGRAMS" variable:
128 bin_PROGRAMS = ... src/foo/foo ...
130 If your contribution is windows-specific, then you should add it
131 to BOTH the "windows_progs" and the EXTRA_PROGRAMS variables:
133 windows_progs = ... src/foo/foo ...
134 EXTRA_PROGRAMS = ... src/foo/foo ...
136 b) Special link libraries
138 If you need to link to special *WINDOWS* libraries, then obviously
139 your program is windows-specific, but also you should add a line
140 in your Makefile.am like this:
142 src_foo_foo_LDADD = -lwinlib
144 Where "src_foo_foo" is the path to your program, where the '/'
145 characters are replaced with '_' characters. Yes, it looks a little
146 funny -- but because our subdirectory has the same name as our
147 program, we get double foo's... Also, 'winlib' is the library
148 that you need. See the src_lpr_lpr_LDADD variable in Makefile.am
151 If, on the other hand, you need to link to some other (cygwin)
152 library that is also more generally available -- like libreadline
153 or libncurses -- then you'll need to do a little more work.
154 For your initial submission, just create an LDADD variable in
155 Makefile.am with -lreadline (or whatever). We'll figure out how
156 to handle it better further down the road. However, make sure
157 to let me know about your special link requirements.
159 src_foo_foo_LDADD = -lreadline
161 One special case is the gettext internationalization libraries.
162 If your program must link with -lintl, then all you need to
163 do is create an LDADD variable as follows:
165 src_foo_foo_LDADD = @LIBINTL@
167 The configuration process will replace @LIBINTL@ with the
168 appropriate -lintl -liconv invocation.
170 Note that you do NOT need to include the popt library in
171 a 'src_foo_foo_LDADD' line; -lpopt will be added automatically...
173 If your app depends on IPC functions, then add @IPCLIBS@
174 to the 'src_foo_foo_LDADD' line.
176 c) man pages and other documentation
178 If you got 'em, copy 'em to your src/foo directory, and add the
179 manpage to the man_MANS variable in Makefile.am like this:
181 man_MANS = ... src/foo/foo.1 ...
183 If there are non-man-page documentation files, you should do
184 one of the following:
185 i) if your app is windows-specific, then create a new
186 variable inside the 'if WITH_WINDOWS_PROGRAMS' section
187 suffixed with '_docs', and list the documentation files
188 foo_docs = src/foo/README src/foo/TODO
189 Also, add those files to the extra_docs variable (which
190 gets automatically included in EXTRA_DIST)
191 extra_docs = src/foo/README src/foo/TODO
192 ii) otherwise, simply create the 'foo_docs' variable
193 outside of the 'if WITH_WINDOWS_PROGRAMS' section
194 These files will be installed into $(docdir)/foo/ so there
195 is no worry that your README will conflict with any other
200 If your contribution consists of more source files than a single
201 .c, then you need to add a variable to Makefile.am that lists all
204 src_foo_foo_SOURCES = foo.c otherfoo.c foo.h
206 Note that this variable should NOT be specified if your program
207 consists merely of a single .c file whose name is the same as
210 If there are .h files in your SOURCES list, then you need to
211 add those .h files to the noinst_HEADERS variable, or the headers
212 would get installed into /usr/include/src/foo/ -- and we don't
215 noinst_HEADERS = ... src/foo/foo.h ...
217 If you have other questions about the Makefile.am file, try to
218 follow the "patterns" established in it by the other programs,
219 or (gasp) read the automake documentation.
221 Libraries are quite complicated to deal with in the cygutils
222 build framework. Fortunately I doubt there will be many of
223 these to worry about, other than cygicons.
225 6) Simplify your #includes.
227 Take a good look at the #include statements in your .c and .h
228 files. If the dependencies are listed in <cygutils>/common.h,
229 then you shouldn't re-include them. If a dependency is NOT
230 listed in common.h, then leave it in your .h/.c file -- for
231 now. We may choose to add them to common.h and add new tests
232 to configure.ac, or we may choose to let your .c file
233 include it directly. However, anything that's already in
234 common.h, remove from your .c/.h file. It's okay to just
235 comment them out, rather than deleting them entirely, if
238 7) Add information to cygutils documentation files:
240 Add a short blurb about your app to <cygutils>/PROGLIST
241 Add your app to the list at the end of the README file
242 Add your name to the AUTHORS file. Don't worry about NEWS;
243 I do that before each release.
247 (You need to have autoconf, autoconf-devel, automake, and
248 automake-devel installed for this to work). Change dir
249 to the top of your checked-out source, and run bootstrap:
254 If you haven't made any mistakes, you should (a) see no
255 errors, and (b) see some new rules in Makefile.in that
256 correspond to your program.
260 Now, just run './configure ; make' as usual. Somewhere
261 amongst the flurry of messages, you should see your application
262 being built. If so, you're almost done. If not, then you
263 need to figure out why. Time to read the auto* documentation...
265 10) Create a patch and ChangeLog entry
270 cvs diff -u > foo.patch
272 If you've already edited the ChangeLog file, make sure to
273 *remove* that chunk from foo.patch. I don't want a PATCH
274 for the ChangeLog, I want the ChangeLog entry itself (ChangeLog
275 patches rarely apply cleanly; it's easier to cut-n-paste. More
280 However, you'll notice that none of the files in your src/foo
281 directory are represented in the patch. That's normal. Remove
282 any .o and .exe files from src/foo, and then just make a tarball
285 tar cvjf foo.tar.bz2 src/foo
289 You should also create a ChangeLog entry. Don't actually edit
290 the ChangeLog itself; create a new file (foo.changelog?) and
291 put your stuff there. It should look like this:
293 2002-03-02 Your Name <your_email_address@domain.com>
295 * src/foo: new directory
296 * src/foo/foo.c: new file
297 * Makefile.am: add program 'foo'
298 * Makefile.in: regenerate
299 * AUTHORS: add yourname for foo
303 Don't list src/foo/Makefile. Do list every original
304 file in src/foo/ (like your man pages, or extra documentation
307 11) Send a notice email to cygwin-apps@cygwin.com, that says "Hey, I
308 finished the integration work neceesary to include 'foo' in the
309 'cygutils' package, as previously agreed on this list." Paste
310 the ChangeLog into that notice. But do NOT send the patch or
311 tarball to the mailing list.
313 Instead, send that to ME, cygwin@cwilson.fastmail.fm. The patch
314 and tarball should be attachments, but paste the ChangeLog entry
315 into the body of the message. Do NOT paste your patch into the
316 body of the email; most mail programs will horrendously distort
317 it if you do). Also, be sure and warn of any special link
318 requirements (cf. section 5a and 5b above).
320 12) Bask in the glow of a job well done.
326 Note to self: how to commit contributions:
328 untar the contribution
329 Add the Changelog entry
331 cvs add src/directory
332 cvs add src/directory/srcfiles
333 cvs commit -m "Add foo contribution"
335 cvs diff | grep Index > foo
336 >>> use 'foo' to add another Changelog entry
337 cvs commit -m "Add foo contribution"