]>
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 | ||
73d352cb CW |
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... | |
2075abba | 172 | |
73d352cb CW |
173 | If your app depends on IPC functions, then add @IPCLIBS@ |
174 | to the 'src_foo_foo_LDADD' line. | |
7ab0751f | 175 | |
41326bf7 | 176 | c) man pages and other documentation |
7ab0751f | 177 | |
41326bf7 | 178 | If you got 'em, copy 'em to your src/foo directory, and add the |
49fd867f | 179 | manpage to the man_MANS variable in Makefile.am like this: |
2075abba | 180 | |
41326bf7 | 181 | man_MANS = ... src/foo/foo.1 ... |
2075abba | 182 | |
65b579cb CW |
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 | |
196 | component's README. | |
2075abba | 197 | |
41326bf7 | 198 | d) Extra files |
2075abba | 199 | |
41326bf7 CW |
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 | |
202 | of them: | |
2075abba | 203 | |
41326bf7 | 204 | src_foo_foo_SOURCES = foo.c otherfoo.c foo.h |
2075abba | 205 | |
49fd867f CW |
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 | |
208 | your program + '.c'. | |
2075abba | 209 | |
41326bf7 CW |
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 | |
213 | want that! | |
2075abba | 214 | |
41326bf7 | 215 | noinst_HEADERS = ... src/foo/foo.h ... |
2075abba | 216 | |
41326bf7 CW |
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. | |
2075abba | 220 | |
65b579cb CW |
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. | |
224 | ||
2075abba CW |
225 | 6) Simplify your #includes. |
226 | ||
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 | |
236 | you prefer. | |
237 | ||
238 | 7) Add information to cygutils documentation files: | |
239 | ||
240 | Add a short blurb about your app to <cygutils>/PROGLIST | |
7ab0751f | 241 | Add your app to the list at the end of the README file |
65b579cb CW |
242 | Add your name to the AUTHORS file. Don't worry about NEWS; |
243 | I do that before each release. | |
2075abba | 244 | |
41326bf7 | 245 | 8) Bootstrap |
2075abba CW |
246 | |
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: | |
250 | ||
251 | cd <cygutils> | |
252 | ./bootstrap | |
253 | ||
254 | If you haven't made any mistakes, you should (a) see no | |
41326bf7 | 255 | errors, and (b) see some new rules in Makefile.in that |
49fd867f | 256 | correspond to your program. |
2075abba | 257 | |
41326bf7 | 258 | 9) Build and test |
2075abba CW |
259 | |
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... | |
264 | ||
41326bf7 | 265 | 10) Create a patch and ChangeLog entry |
2075abba CW |
266 | |
267 | a) PATCH | |
268 | ||
269 | cd <cygutils> | |
270 | cvs diff -u > foo.patch | |
271 | ||
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 | |
276 | below). | |
277 | ||
278 | b) NEW FILES | |
279 | ||
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 | |
283 | ||
284 | cd <cygutils> | |
285 | tar cvjf foo.tar.bz2 src/foo | |
286 | ||
287 | c) CHANGELOG | |
288 | ||
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: | |
292 | ||
293 | 2002-03-02 Your Name <your_email_address@domain.com> | |
294 | ||
295 | * src/foo: new directory | |
2075abba | 296 | * src/foo/foo.c: new file |
5a07c6d2 CW |
297 | * Makefile.am: add program 'foo' |
298 | * Makefile.in: regenerate | |
2075abba CW |
299 | * AUTHORS: add yourname for foo |
300 | * PROGLIST: add foo | |
301 | * README: add foo | |
302 | ||
303 | Don't list src/foo/Makefile. Do list every original | |
304 | file in src/foo/ (like your man pages, or extra documentation | |
305 | files, or headers) | |
306 | ||
41326bf7 CW |
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. | |
2075abba | 312 | |
65b579cb | 313 | Instead, send that to ME, cygwin@cwilson.fastmail.fm. The patch |
41326bf7 CW |
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). | |
319 | ||
320 | 12) Bask in the glow of a job well done. | |
2075abba CW |
321 | |
322 | -- | |
323 | Chuck Wilson | |
324 | cygutils maintainer | |
0d37f40c CW |
325 | |
326 | Note to self: how to commit contributions: | |
327 | apply the patch | |
328 | untar the contribution | |
329 | Add the Changelog entry | |
330 | ./bootstrap | |
331 | cvs add src/directory | |
332 | cvs add src/directory/srcfiles | |
0d37f40c CW |
333 | cvs commit -m "Add foo contribution" |
334 | ./bootstrap | |
335 | cvs diff | grep Index > foo | |
0d37f40c | 336 | >>> use 'foo' to add another Changelog entry |
0d37f40c CW |
337 | cvs commit -m "Add foo contribution" |
338 | cvs tag something | |
339 |