Commit | Line | Data |
---|---|---|
6aaee015 RGS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | CPANPLUS::Hacking | |
6 | ||
7 | =head1 DESCRIPTION | |
8 | ||
9 | This document attempts to describe how to easiest develop with the | |
10 | CPANPLUS environment, how certain things work and why. | |
11 | ||
12 | This is basically a quick-start guide to people who want to add | |
13 | features or patches to CPANPLUS. | |
14 | ||
15 | =head1 OBTAINING CPANPLUS | |
16 | ||
17 | CPANPLUS offers snapshots from the stable and unstable branches. | |
18 | After every patch to either of the branches, the snapshot is | |
19 | automatically updated. | |
20 | ||
21 | You can find the stable branch here (which should be equal to the | |
22 | CPAN release): L<http://p4.elixus.org/snap/cpanplus-dist.tar.gz> | |
23 | ||
24 | And the development branch here: | |
25 | L<http://p4.elixus.org/snap/cpanplus-devel.tar.gz> | |
26 | ||
27 | =head1 INSTALLING CPANPLUS | |
28 | ||
29 | CPANPLUS follows the standard perl module installation process: | |
30 | ||
31 | perl Makefile.PL | |
32 | make | |
33 | make test | |
34 | make install | |
35 | ||
36 | =head1 CONFIGURING CPANPLUS | |
37 | ||
38 | When running C<perl Makefile.PL> you will be prompted to configure. | |
39 | If you have already done so, and merely wish to update the C<Makefile>, | |
40 | simply run: | |
41 | ||
42 | perl Makefile.PL JFDI=1 | |
43 | ||
44 | This will keep your configuration intact. Note however, if there are | |
45 | changes to the default configuration file C<Config.pm-orig>, you should | |
46 | either delete your current config file and reconfigure, or patch your | |
47 | config file from the new entries in C<Config.pm-orig>. | |
48 | ||
49 | =head1 RUNNING CPANPLUS FROM DEVELOPMENT ENVIRONMENT | |
50 | ||
51 | If you'd rather not install the development version to your | |
52 | C<site_perl> directory, that's no problem. You can set your C<PERL5LIB> | |
53 | environment variable to CPANPLUS' C<lib> directory, and you can run it | |
54 | from there. | |
55 | ||
56 | =head1 RUNNING CPANPLUS TESTS | |
57 | ||
58 | Tests are what tells us if CPANPLUS is working. If a test is not working, | |
59 | try to run it explicilty like this: | |
60 | ||
61 | perl -I/path/to/cpanplus/lib t/XX_name_of_test.t 1 | |
62 | ||
63 | The extra '1' makes sure that all the messages and errors (they might | |
64 | be errors we're testing for!) are being printed rather than kept quiet. | |
65 | This is a great way to find out the context of any failures that may | |
66 | occur. | |
67 | ||
68 | If you believe this test failure proves a bug in CPANPLUS, the long | |
69 | output of the test file is something we'd like to see alongside your | |
70 | bug report. | |
71 | ||
72 | =head1 FINDING BUGS | |
73 | ||
74 | Sometimes you might find bugs in CPANPLUS' behaviour. If you encounter | |
75 | these in a development snapshot, we'd appreciate a complete patch (as | |
76 | described below in the L<SENDING PATCHES> section. | |
77 | ||
78 | If it's way over your head, then of course reporting the bug is always | |
79 | better than not reporting it at all. Before you do so though, make | |
80 | sure you have the B<latest> development snapshot, and the bug still | |
81 | persists there. If so, report the bug to this address: | |
82 | ||
83 | cpanplus-devel@lists.sourceforge.net | |
84 | ||
85 | A good C<patch> would have the following characteristics: | |
86 | ||
87 | =over 4 | |
88 | ||
89 | =item Problem description | |
90 | ||
91 | Describe clearly what the bug is you found, and what it should have | |
92 | done instead. | |
93 | ||
94 | =item Program demonstrating the bug | |
95 | ||
96 | Show us how to reproduce the bug, in a simple of a program as possible | |
97 | ||
98 | =item [OPTIONAL] A patch to the test suite to test for the bug | |
99 | ||
100 | Amend our test suite by making sure this bug will be found in this, and | |
101 | future versions of CPANPLUS (see L<SUPPLYING PATCHES>) | |
102 | ||
103 | =item [OPTIONAL] A patch to the code + tests + documentation | |
104 | ||
105 | Fix the bug, update the docs & tests. That way your bug will be gone | |
106 | forever :) | |
107 | ||
108 | =back | |
109 | ||
110 | =head1 SUPPLYING PATCHES | |
111 | ||
112 | Patches are a good thing, and they are welcome. Especially if they fix | |
113 | bugs you've found along the way, or that others have reported. | |
114 | ||
115 | We prefer patches in the following format: | |
116 | ||
117 | =over 4 | |
118 | ||
119 | =item * In C<diff -u> or C<diff -c> format | |
120 | ||
121 | =item * From the root of the snapshot | |
122 | ||
123 | =item * Including patches for code + tests + docs | |
124 | ||
125 | =item * Sent per mail to cpanplus-devel@lists.sourceforge.net | |
126 | ||
127 | =item * With subject containing C<[PATCH]> + description of the patch | |
128 | ||
129 | =back | |
130 | ||
131 | You will always be informed if a patch is applied or rejected, and in | |
132 | case of rejection why that is (perhaps you can tweak the patch to have | |
133 | it accepted after all). | |
134 | ||
135 | =cut | |
136 | ||
137 | __END__ | |
138 | ||
139 | * perl5lib | |
140 | * perl t/foo 1 | |
141 | * patches to cpanplus-devel | |
142 | * snap/devel.tgz |