CONTRIBUTING

   1 Contact
   2 =======
   3
   4 The project homepage is at https://sourceware.org/libabigail
   5
   6 The current libabigail source code can be checked out with:
   7 git clone git://sourceware.org/git/libabigail
   8
   9 The mailing list to send messages and patches to is
  10 libabigail@sourceware.org.
  11
  12 The archives of that list are available at http://sourceware.org/ml/libabigail.
  13
  14 File bugs
  15 =========
  16
  17 Bugs are to be filled in bugzilla at
  18 https://sourceware.org/bugzilla/enter_bug.cgi?product=libabigail
  19
  20 Writing and sending patches
  21 ============================
  22
  23 Please supply patches using git format-patch and git send-email.  If
  24 you don't know how to use git, send-email, fine.  Just use your
  25 favorite email client, attach the patch to a nice message, and send us
  26 the message.
  27
  28 Patches have to be sent by email to libabigail@sourceware.org.
  29
  30 Please read the file COMMIT-LOG-GUIDELINES in the source tree to learn
  31 about how to write the commit log accompanying the patch.
  32
  33 If you are adding a new public header file to the project, or if you
  34 are defining a new entry point to the API of libabigail, please take
  35 some time to read the file VISIBILITY about how you need to handle the
  36 visibility of symbols that are part of the API and ABI of libabigail.
  37
  38 Make sure you sign your patch.  To learn about signing, please read
  39 the "Sign your work" chapter below.
  40
  41 One important thing to be before sending your patch is to launch the
  42 regression tests.
  43
  44 Regression tests
  45 ================
  46
  47 Regression tests are under the directory 'tests'.  They are usually
  48 written in C++ and are especially designed to be easy to debug.  The
  49 idea is that if the test fails, the programmer should just have to
  50 launch them under GDB and debug them right away.  No-bullshit style.
  51
  52 Regression tests are launched by doing:
  53
  54    make check
  55
  56 If you have N processor cores on your machine, you can launch the
  57 tests in parallel to make whole thing go faster by doing:
  58
  59   make -jN -lN check
  60
  61 If you want to test the fabrication of the distribution tarball (this
  62 is important, because that is how we do to actually release the
  63 tarball of the project that you can download from the internet) then
  64 you can do:
  65
  66   make distcheck
  67
  68 This actually builds the tarball, then untars it, configure/compile
  69 the untarred source code and launches the regression checks from
  70 there.
  71
  72 You can also launch this in parallel by doing:
  73
  74   make -jN -lN distcheck
  75
  76 with N being the number of processor core you have on your system.
  77
  78 Please make sure you always launch "make distcheck" before sending a
  79 patch, so that you are sure that we can always build a tarball after
  80 your patch is applied to the source tree.
  81
  82 Launching regression tests in Valgrind
  83 --------------------------------------
  84
  85 To detect memory management errors, the tests of the regression test
  86 suite can be run using Valgrind tools, essentially memcheck and
  87 helgrind.
  88
  89 To do so, please do:
  90
  91   make check-valgrind
  92
  93 This runs the tests under the control of Valgrind memcheck and
  94 helgrind tools.
  95
  96 But then, if you want Valgrind to check the libabigail command line
  97 tools that are *forked* by some of the tests then type:
  98
  99   make check-valgrind-recursive
 100
 101 This one takes a long time.  On my system for instance, it takes an
 102 hour.  But then it checks *everything*.  If you don't have that time,
 103 then "make check-valgrind" is enough, as the regression tests that use
 104 the libabigail *library* directly (as opposed to forking libabigail
 105 command line tools) will be verified.
 106
 107 How tests are organized
 108 -----------------------
 109
 110 There are two kinds of regression tests.  Those that use the
 111 libabigail *library* directly, and those that spawn one of the
 112 libabigail command line tools.
 113
 114 Generally, both are usually made of a loop that churns through a set of input
 115 binaries to compare.  Once the comparison is done, the resulting
 116 report is compared against a reference report that is provided.
 117
 118 Test executable have names that starts with 'runtest*'.  For instance,
 119 under <build-directory>/tests/ you can find tests named
 120 runtestdiffdwarf, runtestabidiff, etc...
 121
 122 If a test executable is named
 123 <build-directory>/tests/runtestdiffdwarf, then its source code is
 124 tests/test-diff-dwarf.cc.  Similarly, the source code of the test
 125 <build-directory>/tests/runtestabidiff is tests/test-abidiff.cc.
 126
 127 The data provided for each test (for instance the input binaries to
 128 compare and the reference report that should result from the
 129 comparison) is to be found under tests/data.  So data for the test
 130 runtestdiffdwarf is to be found under tests/data/test-diff-dwarf.
 131 Data for the test runtestabidiff is to be found under
 132 tests/data/test-abidiff.cc.
 133
 134 So adding your own tests usually just amounts to adding the input
 135 right input into the right sub-directory of tests/data/.  To do so,
 136 look at several tests/test-*.cc to see which one you'd like to add
 137 some input binaries to be compared in.
 138
 139 Then once you know which tests/test-*.cc you'd like to extend, and if
 140 you added your input binaries and reference reports (maybe other
 141 things too) to the right sub-director of tests/data/, you just need to
 142 extend the array of input binaries/reference reports that the test
 143 walks to perform the comparisons.  It's generally a global variable
 144 before the main() function of the test.  In test-diff-dwarf.cc, for
 145 instance, the variable name is "in_out_specs".  You just have to add a
 146 new entry to that array; that new entry contains the paths to your new
 147 input binaries and reference reports.  Just read the code in there and
 148 use your brains.  It should be straight forward.
 149
 150 Ah, also, if you added new files for the tests, then the build system
 151 needs to be told that those files have to be added to the distribution
 152 tarball when we do "make dist" (or make distcheck).  To do so, please
 153 make sure to add your new test input files to the
 154 tests/data/Makefile.am file, in the EXTRA_DIST variable.  Look at how
 155 things are organized in that file, and please do things similarly.
 156
 157 Sign your work
 158 ==============
 159
 160 To facilitate tracking of who did what, we've adopted a "sign-off"
 161 procedure for patches based on the procedure used by the Linux kernel
 162 project.
 163
 164 The sign-off is a simple line at the end of the explanation for the
 165 patch, which certifies that you wrote it or otherwise have the right
 166 to pass it on as a patch under an appropriate license. The rules are
 167 pretty simple: if you can certify the below:
 168
 169         Developer's Certificate of Origin
 170
 171         By making a contribution to this project, I certify that:
 172
 173         (a) The contribution was created in whole or in part by me,
 174             and I have the right to submit the contribution under the
 175             license indicated in, or otherwise designated as being
 176             applicable to, the file.
 177
 178         (b) The contribution was provided directly to me by some other
 179             person who certified (a), and I have not modified it.
 180
 181         (c) I understand and agree that the project and the
 182             contribution are public and that a record of the
 183             contribution (including all personal information I submit
 184             with it, including my sign-off) is maintained indefinitely
 185             and may be redistributed.
 186
 187 then you just add a line saying
 188
 189 Signed-off-by: Random J Developer <random@developer.example.org>
 190
 191 using your real name (sorry, no pseudonyms or anonymous contributions.)
 192
 193 git commit --signoff will add such a Signed-off-by line at the end of
 194 the commit log message for you.
 195
 196 Modifying the website
 197 =====================
 198
 199 The source code of the website of libabigail is stored in CVS (sigh,
 200 yeah, that is so old school).  You can check out that web source code
 201 by doing:
 202
 203     CVS_RSH=ssh cvs -z9 -d :ext:user@sourceware.org:/cvs/libabigail/ co htdocs
 204
 205 where 'user' is your username on the sourceware system.
 206 Alternatively, you can check out the the web source code anonymously,
 207 if you don't have any user account on the sourceware system by doing:
 208
 209     export CVSROOT=:pserver:anoncvs@cygwin.com:/cvs/libabigail
 210     cvs login
 211     (the CVS anonymous password to use is "anoncvs")
 212     cvs checkout htdocs
 213
 214
 215 Happy Hacking!