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 (a] 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. 207
