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 Don't just send me yourfile.c and expect me to
7 do all the integration work.
9 You need to do more than merely insure that it builds
10 on your machine with a simple
12 gcc -o yourfile.exe yourfile.c -lthislibrary -lthatlibrary
14 In addition to that, you need to check out the cygutils
15 source and integrate yourfile into the whole system. Instructions
16 follow below. However, you'll notice that it's quite a bit
17 of work. You may want to send an exploratory email to
18 cygwin@cygwin.com and explain your programs behavior, what
19 need it fills, and get pre-clearance for eventual inclusion
20 into cygutils before embarking on the journey outlined below.
21 Also, note that I will not fix your bugs. If, at some time
22 after your program is accepted into cygutils, I (as cygutils
23 maintainer) get a bug report on your program, I will forward
24 it to you. If you don't fix it or respond within a reasonable
25 time, I will remove it from the distribution.
27 ------------------------------------------------------
29 Okay, now that we're past that unpleasantness, here's how to
30 integrate your spiffy new utility. First, let's assume that
31 your spiffy utility is called 'foo', and its source is in 'foo.c'.
33 The simple 12 step program:
34 ---------------------------
36 1) Get the cygutils source
38 cvs -d:pserver:anoncvs@sources.redhat.com:/cvs/cygwin-apps login
39 use 'anoncvs' as the password
40 cvs -z3 -d:pserver:anoncvs@sources.redhat.com:/cvs/cygwin-apps co cygutils
42 you now have a 'cygutils' directory with the existing source.
44 2) License information
46 make sure that all .c and .h files in your contribution
47 have license information: preferably GPL, but other
48 open licenses are acceptable, too. See the top of
49 src/lpr/lpr.c for an example.
51 a) if your license is not GPL or BSD-no-advert, then
52 you must also include a copy of the ENTIRE license
53 in the licenses subdirectory. (Most of the time,
54 the blurb in the .c or .h file is just that: a short
55 blurb, with a reference to the full text elsewhere)
59 create a new directory for your contribution underneath 'src'
60 In our case, we will do this:
64 copy your source into the new directory
65 cp <location>/foo.c <cygutils>/src/foo/
67 4) Modify your source code
69 Add the following snippet to the beginning of your .c and .h(*)
70 files, just after the license information:
77 a) If your contribution has its own .h file(s), the entire .h file
78 should be "guarded" as follows:
80 /* license information */
83 /* the config.h/common.h stuff */
84 /* your header stuff */
87 the "_FOO_H" identifier should be changed to match the filename
88 of your header file. Thus, "bob.h" would be guarded with _BOB_H.
92 Create a Makefile.am file in your 'foo' directory. If your
93 contribution will build on non-windows platforms in addition to
94 cygwin, then Makefile.am should look like this:
96 ## Makefile.am -- Process this file with automake to produce Makefile.in
97 INCLUDES = -I$(top_builddir) -I$(top_srcdir)
101 (Yes, really. That's it). If your contribution is windows-specific,
102 like lpr or mkshortcut or the [put|get]clip programs, then your
103 Makefile.am should look like:
105 ## Makefile.am -- Process this file with automake to produce Makefile.in
106 INCLUDES = -I$(top_builddir) -I$(top_srcdir)
107 if WITH_WINDOWS_PROGRAMS
110 bin_PROGRAMS = $(windows_progs)
114 a) Special link libraries
116 If you need to link to special *WINDOWS* libraries, then obviously
117 your program is windows-specific, but also you should add a line
118 in your Makefile.am like this:
122 Where foo is your program name, and winlib is the library you need.
123 See src/lpr/Makefile.am or src/mkshortcut/Makefile.am for
126 If, on the other hand, you need to link to some other (cygwin)
127 library that is also more generally available -- like libreadline
128 or libncurses -- then you'll need to do a little more work.
129 For your initial submission, just add the -lreadline (or whatever)
130 command to your Makefile.am foo_LDADD line. However, make sure
131 to let me know about your special link requirements.
133 Note that you do NOT need to include the following libraries in
134 a 'foo_LDADD' line; these will be added automatically...
136 -lintl -lcygipc -lpopt (that is, gettext, cygipc, or popt)
138 b) man pages and other documentation
140 If you got 'em, copy 'em to your foo directory, and add a line
141 to your Makefile.am like this:
145 If there are non-man-page documentation files, you should add
148 EXTRA_DIST = foo.README
150 However, there is no provisiion for actually INSTALLING these
151 additional documentation files. At least not yet.
155 If your contribution consists of more source files than a single
156 .c, then you need to add a line that lists all of them in your
159 foo_SOURCES = foo.c otherfoo.c foo.h
161 If there are .h files in that list, you should also add a line
164 noinst_HEADERS = foo.h
166 If you have other questions about the Makefile.am file, consult
167 the other ones already in cygutils as examples, or read the
168 automake documentation.
170 6) Simplify your #includes.
172 Take a good look at the #include statements in your .c and .h
173 files. If the dependencies are listed in <cygutils>/common.h,
174 then you shouldn't re-include them. If a dependency is NOT
175 listed in common.h, then leave it in your .h/.c file -- for
176 now. We may choose to add them to common.h and add new tests
177 to configure.ac, or we may choose to let your .c file
178 include it directly. However, anything that's already in
179 common.h, remove from your .c/.h file. It's okay to just
180 comment them out, rather than deleting them entirely, if
183 7) Add information to cygutils documentation files:
185 Add a short blurb about your app to <cygutils>/PROGLIST
186 Add your app to the list at the end of the README file
187 Add your name to the AUTHORS file.
189 8) Hook your directory into the package build structure
191 Add the name of your directory in src to the list in
194 Add your Makefile to the list at the end of configure.ac
198 (You need to have autoconf, autoconf-devel, automake, and
199 automake-devel installed for this to work). Change dir
200 to the top of your checked-out source, and run bootstrap:
205 If you haven't made any mistakes, you should (a) see no
206 errors, and (b) see a Makefile.in file added to your foo
211 Now, just run './configure ; make' as usual. Somewhere
212 amongst the flurry of messages, you should see your application
213 being built. If so, you're almost done. If not, then you
214 need to figure out why. Time to read the auto* documentation...
216 11) Create a patch and ChangeLog entry
221 cvs diff -u > foo.patch
223 If you've already edited the ChangeLog file, make sure to
224 *remove* that chunk from foo.patch. I don't want a PATCH
225 for the ChangeLog, I want the ChangeLog entry itself (ChangeLog
226 patches rarely apply cleanly; it's easier to cut-n-paste. More
231 However, you'll notice that none of the files in your src/foo
232 directory are represented in the patch. That's normal. Remove
233 any .o and .exe files from src/foo, and then just make a tarball
236 tar cvjf foo.tar.bz2 src/foo
240 You should also create a ChangeLog entry. Don't actually edit
241 the ChangeLog itself; create a new file (foo.changelog?) and
242 put your stuff there. It should look like this:
244 2002-03-02 Your Name <your_email_address@domain.com>
246 * src/foo: new directory
247 * src/foo/Makefile.am: new file
248 * src/foo/Makefile.in: new file
249 * src/foo/foo.c: new file
250 * src/Makefile.am: add subdirectory foo
251 * src/Makefile.in: regenerate
252 * configure.ac: add src/foo/Makefile to output list
253 * AUTHORS: add yourname for foo
257 Don't list src/foo/Makefile. Do list every original
258 file in src/foo/ (like your man pages, or extra documentation
261 12) Send an email to cygwin@cygwin.com with the patch and the
262 tarball as attachements. Paste your changelog into the body
263 of the message -- or you can send it as an attachment. (Do NOT
264 put your patch into the body of the email; most mail programs
265 will horrendously distort it if you do).
267 In the body of your email, Describe what your program does, why
268 it's needed, and why you think it should be added to the
269 cygutils package. Also explain why (or state that) existing
270 tools will not meet the need your program does. Also, be
271 sure and warn of any special link requirements (cf. section