]>
Commit | Line | Data |
---|---|---|
2075abba CW |
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: | |
5 | ||
41326bf7 CW |
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 | |
13 | cygutils). | |
14 | ||
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. | |
22 | ||
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 | |
27 | program does. | |
28 | ||
29 | Second, once you're obtained agreement that yourfile.c | |
30 | should be added to cygutils: | |
31 | ||
2075abba CW |
32 | Don't just send me yourfile.c and expect me to |
33 | do all the integration work. | |
34 | ||
35 | You need to do more than merely insure that it builds | |
36 | on your machine with a simple | |
37 | ||
38 | gcc -o yourfile.exe yourfile.c -lthislibrary -lthatlibrary | |
39 | ||
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 | |
41326bf7 | 43 | of work. Again, are you SURE you want it to become part |
5a07c6d2 | 44 | of cygutils? Making a standalone program is a lot easier... |
41326bf7 | 45 | |
2075abba CW |
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. | |
51 | ||
52 | ------------------------------------------------------ | |
53 | ||
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'. | |
57 | ||
58 | The simple 12 step program: | |
59 | --------------------------- | |
60 | ||
61 | 1) Get the cygutils source | |
62 | ||
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 | |
66 | ||
67 | you now have a 'cygutils' directory with the existing source. | |
68 | ||
69 | 2) License information | |
70 | ||
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. | |
75 | ||
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) | |
81 | ||
0c884560 CW |
82 | You should also add it to the licenses variable in |
83 | the toplevel Makefile.am: e.g. | |
84 | ||
85 | licenses = ... licenses/COPYING.MPL ... | |
86 | ||
2075abba CW |
87 | 3) Make a home |
88 | ||
89 | create a new directory for your contribution underneath 'src' | |
90 | In our case, we will do this: | |
91 | cd cygutils/src | |
92 | mkdir foo | |
93 | ||
94 | copy your source into the new directory | |
95 | cp <location>/foo.c <cygutils>/src/foo/ | |
96 | ||
97 | 4) Modify your source code | |
98 | ||
99 | Add the following snippet to the beginning of your .c and .h(*) | |
100 | files, just after the license information: | |
101 | ||
102 | #if HAVE_CONFIG_H | |
103 | #include "config.h" | |
104 | #endif | |
105 | #include "common.h" | |
106 | ||
107 | a) If your contribution has its own .h file(s), the entire .h file | |
108 | should be "guarded" as follows: | |
109 | ||
110 | /* license information */ | |
111 | #ifndef _FOO_H | |
112 | #define _FOO_H | |
113 | /* the config.h/common.h stuff */ | |
114 | /* your header stuff */ | |
115 | #endif /* !_FOO_H */ | |
116 | ||
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. | |
119 | ||
41326bf7 | 120 | Naturally, the header files should also be copied into src/foo/. |
2075abba | 121 | |
41326bf7 | 122 | 5) Modify cygutils/Makefile.am |
2075abba | 123 | |
41326bf7 CW |
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: | |
2075abba | 127 | |
41326bf7 | 128 | bin_PROGRAMS = ... src/foo/foo ... |
2075abba | 129 | |
41326bf7 CW |
130 | If your contribution is windows-specific, then you should add it |
131 | to BOTH the "windows_progs" and the EXTRA_PROGRAMS variables: | |
2075abba | 132 | |
49fd867f | 133 | windows_progs = ... src/foo/foo ... |
41326bf7 CW |
134 | EXTRA_PROGRAMS = ... src/foo/foo ... |
135 | ||
136 | b) Special link libraries | |
2075abba | 137 | |
41326bf7 CW |
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: | |
141 | ||
142 | src_foo_foo_LDADD = -lwinlib | |
2075abba | 143 | |
41326bf7 CW |
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 | |
149 | for an example. | |
150 | ||
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 | |
49fd867f | 156 | to handle it better further down the road. However, make sure |
41326bf7 | 157 | to let me know about your special link requirements. |
2075abba | 158 | |
49fd867f | 159 | src_foo_foo_LDADD = -lreadline |
2075abba | 160 | |
53feab08 CW |
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: | |
164 | ||
639cf7c5 | 165 | src_foo_foo_LDADD = @LIBINTL@ |
53feab08 | 166 | |
639cf7c5 | 167 | The configuration process will replace @LIBINTL@ with the |
53feab08 CW |
168 | appropriate -lintl -liconv invocation. |
169 | ||
41326bf7 CW |
170 | Note that you do NOT need to include the following libraries in |
171 | a 'src_foo_foo_LDADD' line; these will be added automatically... | |
2075abba | 172 | |
53feab08 | 173 | -lcygipc -lpopt (that is, cygipc or popt) |
7ab0751f | 174 | |
41326bf7 | 175 | c) man pages and other documentation |
7ab0751f | 176 | |
41326bf7 | 177 | If you got 'em, copy 'em to your src/foo directory, and add the |
49fd867f | 178 | manpage to the man_MANS variable in Makefile.am like this: |
2075abba | 179 | |
41326bf7 | 180 | man_MANS = ... src/foo/foo.1 ... |
2075abba | 181 | |
41326bf7 | 182 | If there are non-man-page documentation files, you should those |
0c884560 CW |
183 | files to the extra_docs variable (which gets automatically |
184 | included in EXTRA_DIST) | |
2075abba | 185 | |
0c884560 | 186 | extra_docs = ... src/foo/foo.README ... |
2075abba | 187 | |
41326bf7 CW |
188 | However, there is no provisiion for actually INSTALLING these |
189 | additional documentation files. At least not yet. | |
2075abba | 190 | |
41326bf7 | 191 | d) Extra files |
2075abba | 192 | |
41326bf7 CW |
193 | If your contribution consists of more source files than a single |
194 | .c, then you need to add a variable to Makefile.am that lists all | |
195 | of them: | |
2075abba | 196 | |
41326bf7 | 197 | src_foo_foo_SOURCES = foo.c otherfoo.c foo.h |
2075abba | 198 | |
49fd867f CW |
199 | Note that this variable should NOT be specified if your program |
200 | consists merely of a single .c file whose name is the same as | |
201 | your program + '.c'. | |
2075abba | 202 | |
41326bf7 CW |
203 | If there are .h files in your SOURCES list, then you need to |
204 | add those .h files to the noinst_HEADERS variable, or the headers | |
205 | would get installed into /usr/include/src/foo/ -- and we don't | |
206 | want that! | |
2075abba | 207 | |
41326bf7 | 208 | noinst_HEADERS = ... src/foo/foo.h ... |
2075abba | 209 | |
41326bf7 CW |
210 | If you have other questions about the Makefile.am file, try to |
211 | follow the "patterns" established in it by the other programs, | |
212 | or (gasp) read the automake documentation. | |
2075abba CW |
213 | |
214 | 6) Simplify your #includes. | |
215 | ||
216 | Take a good look at the #include statements in your .c and .h | |
217 | files. If the dependencies are listed in <cygutils>/common.h, | |
218 | then you shouldn't re-include them. If a dependency is NOT | |
219 | listed in common.h, then leave it in your .h/.c file -- for | |
220 | now. We may choose to add them to common.h and add new tests | |
221 | to configure.ac, or we may choose to let your .c file | |
222 | include it directly. However, anything that's already in | |
223 | common.h, remove from your .c/.h file. It's okay to just | |
224 | comment them out, rather than deleting them entirely, if | |
225 | you prefer. | |
226 | ||
227 | 7) Add information to cygutils documentation files: | |
228 | ||
229 | Add a short blurb about your app to <cygutils>/PROGLIST | |
7ab0751f | 230 | Add your app to the list at the end of the README file |
2075abba CW |
231 | Add your name to the AUTHORS file. |
232 | ||
41326bf7 | 233 | 8) Bootstrap |
2075abba CW |
234 | |
235 | (You need to have autoconf, autoconf-devel, automake, and | |
236 | automake-devel installed for this to work). Change dir | |
237 | to the top of your checked-out source, and run bootstrap: | |
238 | ||
239 | cd <cygutils> | |
240 | ./bootstrap | |
241 | ||
242 | If you haven't made any mistakes, you should (a) see no | |
41326bf7 | 243 | errors, and (b) see some new rules in Makefile.in that |
49fd867f | 244 | correspond to your program. |
2075abba | 245 | |
41326bf7 | 246 | 9) Build and test |
2075abba CW |
247 | |
248 | Now, just run './configure ; make' as usual. Somewhere | |
249 | amongst the flurry of messages, you should see your application | |
250 | being built. If so, you're almost done. If not, then you | |
251 | need to figure out why. Time to read the auto* documentation... | |
252 | ||
41326bf7 | 253 | 10) Create a patch and ChangeLog entry |
2075abba CW |
254 | |
255 | a) PATCH | |
256 | ||
257 | cd <cygutils> | |
258 | cvs diff -u > foo.patch | |
259 | ||
260 | If you've already edited the ChangeLog file, make sure to | |
261 | *remove* that chunk from foo.patch. I don't want a PATCH | |
262 | for the ChangeLog, I want the ChangeLog entry itself (ChangeLog | |
263 | patches rarely apply cleanly; it's easier to cut-n-paste. More | |
264 | below). | |
265 | ||
266 | b) NEW FILES | |
267 | ||
268 | However, you'll notice that none of the files in your src/foo | |
269 | directory are represented in the patch. That's normal. Remove | |
270 | any .o and .exe files from src/foo, and then just make a tarball | |
271 | ||
272 | cd <cygutils> | |
273 | tar cvjf foo.tar.bz2 src/foo | |
274 | ||
275 | c) CHANGELOG | |
276 | ||
277 | You should also create a ChangeLog entry. Don't actually edit | |
278 | the ChangeLog itself; create a new file (foo.changelog?) and | |
279 | put your stuff there. It should look like this: | |
280 | ||
281 | 2002-03-02 Your Name <your_email_address@domain.com> | |
282 | ||
283 | * src/foo: new directory | |
2075abba | 284 | * src/foo/foo.c: new file |
5a07c6d2 CW |
285 | * Makefile.am: add program 'foo' |
286 | * Makefile.in: regenerate | |
2075abba CW |
287 | * AUTHORS: add yourname for foo |
288 | * PROGLIST: add foo | |
289 | * README: add foo | |
290 | ||
291 | Don't list src/foo/Makefile. Do list every original | |
292 | file in src/foo/ (like your man pages, or extra documentation | |
293 | files, or headers) | |
294 | ||
41326bf7 CW |
295 | 11) Send a notice email to cygwin-apps@cygwin.com, that says "Hey, I |
296 | finished the integration work neceesary to include 'foo' in the | |
297 | 'cygutils' package, as previously agreed on this list." Paste | |
298 | the ChangeLog into that notice. But do NOT send the patch or | |
299 | tarball to the mailing list. | |
2075abba | 300 | |
41326bf7 CW |
301 | Instead, send that to ME, cwilson@ece.gatech.edu. The patch |
302 | and tarball should be attachments, but paste the ChangeLog entry | |
303 | into the body of the message. Do NOT paste your patch into the | |
304 | body of the email; most mail programs will horrendously distort | |
305 | it if you do). Also, be sure and warn of any special link | |
306 | requirements (cf. section 5a and 5b above). | |
307 | ||
308 | 12) Bask in the glow of a job well done. | |
2075abba CW |
309 | |
310 | -- | |
311 | Chuck Wilson | |
312 | cygutils maintainer | |
0d37f40c CW |
313 | |
314 | Note to self: how to commit contributions: | |
315 | apply the patch | |
316 | untar the contribution | |
317 | Add the Changelog entry | |
318 | ./bootstrap | |
319 | cvs add src/directory | |
320 | cvs add src/directory/srcfiles | |
0d37f40c CW |
321 | cvs commit -m "Add foo contribution" |
322 | ./bootstrap | |
323 | cvs diff | grep Index > foo | |
0d37f40c | 324 | >>> use 'foo' to add another Changelog entry |
0d37f40c CW |
325 | cvs commit -m "Add foo contribution" |
326 | cvs tag something | |
327 |