Jeff Brown | 7a33c86 | 2011-02-02 14:00:44 -0800 | [diff] [blame] | 1 | And when you drive for hours, arrive to find you nowhere gone, you've just been |
| 2 | mouthing "brum, brum", rocking wheel, of course you have, the heap is rusted |
| 3 | through and off the road since you drove drunk through thirteen school yards, |
| 4 | laughing like Prescott. |
| 5 | |
| 6 | Then welcome, ah, oo costrinzi welcome, in OProfile. |
| 7 | |
| 8 | Please talk to the list before starting on something. We're not too scary. |
| 9 | |
| 10 | You can find some documentation on how OProfile works in doc/internals.html |
| 11 | |
| 12 | Here's a short list of some stuff you need to know to get started. Don't forget |
| 13 | to read doc/CodingStyle |
| 14 | |
| 15 | Source organisation |
| 16 | ------------------- |
| 17 | |
| 18 | module/ |
| 19 | |
| 20 | The 2.4 module code. Sub-directories contain architecture-specific code. |
| 21 | |
| 22 | daemon/ |
| 23 | |
| 24 | The daemon. liblegacy/ contains the daemon core for 2.4 |
| 25 | |
| 26 | utils/ |
| 27 | |
| 28 | Scripts for managing the daemon etc. |
| 29 | |
| 30 | doc/ |
| 31 | |
| 32 | User and developer documentation |
| 33 | |
| 34 | events/ |
| 35 | |
| 36 | Textual performance counter event descriptions. |
| 37 | |
| 38 | libpp/ |
| 39 | |
| 40 | Classes for handling profiles |
| 41 | |
| 42 | pp/ |
| 43 | |
| 44 | The post-profiling tools for showing results |
| 45 | |
| 46 | libabi/ |
| 47 | |
| 48 | opimport and its ABI support library |
| 49 | |
| 50 | libdb/ |
| 51 | |
| 52 | The sample file access library |
| 53 | |
| 54 | libop/ |
| 55 | |
| 56 | C language oprofile-specific helper stuff |
| 57 | |
| 58 | libopt++/ |
| 59 | |
| 60 | A simple C++ library for parsing command lines |
| 61 | |
| 62 | libregex/ |
| 63 | |
| 64 | C++ demangling pattern matching for smart demangling feature. |
| 65 | |
| 66 | libutil/ |
| 67 | libutil++/ |
| 68 | |
| 69 | Generic helpers |
| 70 | |
| 71 | gui/ |
| 72 | |
| 73 | The GUI for starting oprofile |
| 74 | |
| 75 | m4/ |
| 76 | |
| 77 | Autoconf macros for ./configure stage |
| 78 | |
| 79 | Tools |
| 80 | ----- |
| 81 | |
| 82 | You'll need autoconf 2.13+ and automake 2.5+ when using CVS. Don't forget to |
| 83 | autogen.sh first. |
| 84 | |
| 85 | We still currently support gcc 2.91.66. Please bear this in mind. |
| 86 | |
| 87 | Shell Scripts |
| 88 | ------------- |
| 89 | |
| 90 | Any shell scripts should aim to be as compatible as possible with different |
| 91 | shells and "bashisms" etc. should not be used. Busybox is often used instead |
| 92 | of bash on embedded devices for example. |
| 93 | |
| 94 | Making patches, commit rights |
| 95 | ----------------------------- |
| 96 | |
| 97 | Patches should be in diff -u format, appliable by patch -p1 in the top-level |
| 98 | source directory. Patches should not include changes to generated files. |
| 99 | |
| 100 | Even trivial patches must have a change log entry in the usual format (see |
| 101 | ChangeLog). Refer to bug numbers in the change log if relevant. |
| 102 | |
| 103 | When you submit a patch, we ask that you include a "Signed-off-by" |
| 104 | line; for example: |
| 105 | Signed-off-by: Random J Developer <random@developer.example.org> |
| 106 | |
| 107 | Including this line with your patch implies that you have read and comply with |
| 108 | the "Developer's Certificate of Origin 1.1" (DCO). This is the same process |
| 109 | the kernel community uses to try to ensure the originality of patches. The |
| 110 | DCO can be found in <kernel-source>/Documentation/SubmittingPatches, item 11, |
| 111 | "Sign your work". For convenience, a copy of the DCO is included below. |
| 112 | |
| 113 | Developer's Certificate of Origin 1.1 |
| 114 | |
| 115 | By making a contribution to this project, I certify that: |
| 116 | |
| 117 | (a) The contribution was created in whole or in part by me and I |
| 118 | have the right to submit it under the open source license |
| 119 | indicated in the file; or |
| 120 | |
| 121 | (b) The contribution is based upon previous work that, to the best |
| 122 | of my knowledge, is covered under an appropriate open source |
| 123 | license and I have the right under that license to submit that |
| 124 | work with modifications, whether created in whole or in part |
| 125 | by me, under the same open source license (unless I am |
| 126 | permitted to submit under a different license), as indicated |
| 127 | in the file; or |
| 128 | |
| 129 | (c) The contribution was provided directly to me by some other |
| 130 | person who certified (a), (b) or (c) and I have not modified |
| 131 | it. |
| 132 | |
| 133 | (d) I understand and agree that this project and the contribution |
| 134 | are public and that a record of the contribution (including all |
| 135 | personal information I submit with it, including my sign-off) is |
| 136 | maintained indefinitely and may be redistributed consistent with |
| 137 | this project or the open source license(s) involved. |
| 138 | |
| 139 | |
| 140 | |
| 141 | If you make a change visible to the user in some way, you should check the |
| 142 | website for any needed changes. Patches to oprofile-www CVS are preferred |
| 143 | but a notification of what needs changing is good enough. Any changes that |
| 144 | affect the docs (man-pages or oprofile.xml) must include documentation updates |
| 145 | as appropriate. Also see below. |
| 146 | |
| 147 | You may after a while be given direct commit rights. You should be |
| 148 | subscribed to both the main list and the commits mailing list if you do. |
| 149 | Your cvs commit message only needs to briefly describe what your change |
| 150 | does - the change log should have the detailed description. Any |
| 151 | non-trivial change needs approval from either John, Phil or Maynard, |
| 152 | unless stated otherwise. The CVS tree will freeze occassionally for |
| 153 | release, in which case no commits are allowed at all without agreement |
| 154 | of John, Phil, or Maynard. CVS admin changes (-kb, .cvsignore etc.) do |
| 155 | not need a change log, and neither does changes to TODO. If you make a |
| 156 | change that affects the user (feature improvement, new feature, bug fix, |
| 157 | UI change), see the next section. |
| 158 | |
| 159 | The oprofile website |
| 160 | -------------------- |
| 161 | |
| 162 | The oprofile website source is stored in the oprofile-www CVS module, excepting |
| 163 | the doc/ and srcdoc/ directories, which are updated by hand at release time. |
| 164 | The visible website (http://oprofile.sf.net/) must always describe the last |
| 165 | *released* version of OProfile, but the CVS contents should be up to date with |
| 166 | the CVS code. This means that if you make a user-visible change as described |
| 167 | in the last section, you should update the files in oprofile-www and commit. |
| 168 | You can do "cvs update" in home/groups/o/op/oprofile/htdocs/cvs on sourceforge |
| 169 | to get http://oprofile.sf.net/cvs/, so you can check your changes work (and |
| 170 | validate: see http://www.htmlhelp.com/tools/validator/). |
| 171 | |
| 172 | Any user-visible change should have a short description in the file |
| 173 | release-notes/release-<nextversion> in the oprofile-www CVS module. |
| 174 | Do not document bug fixes that were not in the last released version. |
| 175 | |
| 176 | CVS branches |
| 177 | ------------ |
| 178 | |
| 179 | You may need at some point to do your work on a CVS branch, if it's |
| 180 | particularly invasive. CVS is a PITA in this respect unfortunately. It's |
| 181 | strongly recommended that you merge changes from the trunk to your branch at |
| 182 | regular intervals. |
| 183 | |
| 184 | To create a branch, create a branch tag : |
| 185 | |
| 186 | cvs rtag -b BRANCH_WHATEVER oprofile |
| 187 | |
| 188 | And add a merge tag (in the trunk repository): |
| 189 | |
| 190 | cvs rtag BRANCH_WHATEVER_MERGE oprofile |
| 191 | |
| 192 | Now make your changes on the branch as you wish. When you want to merge some |
| 193 | fixes from the trunk in your branch, do something like this on a branch |
| 194 | checkout : |
| 195 | |
| 196 | cvs update -j BRANCH_WHATEVER_MERGE -j HEAD |
| 197 | |
| 198 | Fix up any conflicts and commit it the changes to the branch. Now move the |
| 199 | merge tag along for the next merge (in the trunk repository) : |
| 200 | |
| 201 | cvs rtag -F BRANCH_WHATEVER_MERGE oprofile |
| 202 | |
| 203 | When the time comes to merge the branch changes back into the trunk, I |
| 204 | recommend just doing a diff -Naur on the two trees, which will make sure CVS |
| 205 | hasn't done anything unusual. Don't forget to list your branch on the website |
| 206 | CVS page. |