4 The project homepage is at https://sourceware.org/libabigail
6 The current libabigail source code can be checked out with:
7 git clone git://sourceware.org/git/libabigail
9 The mailing list to send messages and patches to is
10 libabigail@sourceware.org.
12 The archives of that list are available at http://sourceware.org/ml/libabigail.
17 Bugs are to be filled in bugzilla at
18 https://sourceware.org/bugzilla/enter_bug.cgi?product=libabigail
20 Writing and sending patches
21 ============================
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
28 Patches have to be sent by email to libabigail@sourceware.org.
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.
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.
38 Make sure you sign your patch. To learn about signing, please read
39 the "Sign your work" chapter below.
41 One important thing to be before sending your patch is to launch the
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.
52 Regression tests are launched by doing:
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:
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
68 This actually builds the tarball, then untars it, configure/compile
69 the untarred source code and launches the regression checks from
72 You can also launch this in parallel by doing:
74 make -jN -lN distcheck
76 with N being the number of processor core you have on your system.
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.
82 Launching regression tests in Valgrind
83 --------------------------------------
85 To detect memory management errors, the tests of the regression test
86 suite can be run using Valgrind tools, essentially memcheck and
93 This runs the tests under the control of Valgrind memcheck and
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:
99 make check-valgrind-recursive
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.
107 How tests are organized
108 -----------------------
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.
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.
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...
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.
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.
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.
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.
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.
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
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:
169 Developer's Certificate of Origin
171 By making a contribution to this project, I certify that:
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.
178 (b) The contribution was provided directly to me by some other
179 person who certified (a), and I have not modified it.
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.
187 then you just add a line saying
189 Signed-off-by: Random J Developer <random@developer.example.org>
191 using your real name (sorry, no pseudonyms or anonymous contributions.)
193 git commit --signoff will add such a Signed-off-by line at the end of
194 the commit log message for you.
196 Modifying the website
197 =====================
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
203 CVS_RSH=ssh cvs -z9 -d :ext:user@sourceware.org:/cvs/libabigail/ co htdocs
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:
209 export CVSROOT=:pserver:anoncvs@cygwin.com:/cvs/libabigail
211 (the CVS anonymous password to use is "anoncvs")