Contact ======= The project homepage is at https://sourceware.org/libabigail The current libabigail source code can be checked out with: git clone git://sourceware.org/git/libabigail The mailing list to send messages and patches to is libabigail@sourceware.org. The archives of that list are available at http://sourceware.org/ml/libabigail. File bugs ========= Bugs are to be filled in bugzilla at https://sourceware.org/bugzilla/enter_bug.cgi?product=libabigail Writing and sending patches ============================ Please supply patches using git format-patch and git send-email. If you don't know how to use git, send-email, fine. Just use your favorite email client, attach the patch to a nice message, and send us the message. Patches have to be sent by email to libabigail@sourceware.org. Please read the file COMMIT-LOG-GUIDELINES in the source tree to learn about how to write the commit log accompanying the patch. If you are adding a new public header file to the project, or if you are defining a new entry point to the API of libabigail, please take some time to read the file VISIBILITY about how you need to handle the visibility of symbols that are part of the API and ABI of libabigail. Make sure you sign your patch. To learn about signing, please read the "Sign your work" chapter below. One important thing to be before sending your patch is to launch the regression tests. Regression tests ================ Regression tests are under the directory 'tests'. They are usually written in C++ and are especially designed to be easy to debug. The idea is that if the test fails, the programmer should just have to launch them under GDB and debug them right away. No-bullshit style. Regression tests are launched by doing: make check If you have N processor cores on your machine, you can launch the tests in parallel to make whole thing go faster by doing: make -jN -lN check If you want to test the fabrication of the distribution tarball (this is important, because that is how we do to actually release the tarball of the project that you can download from the internet) then you can do: make distcheck This actually builds the tarball, then untars it, configure/compile the untarred source code and launches the regression checks from there. You can also launch this in parallel by doing: make -jN -lN distcheck with N being the number of processor core you have on your system. Please make sure you always launch "make distcheck" before sending a patch, so that you are sure that we can always build a tarball after your patch is applied to the source tree. Launching regression tests in Valgrind -------------------------------------- To detect memory management errors, the tests of the regression test suite can be run using Valgrind tools, essentially memcheck and helgrind. To do so, please do: make check-valgrind This runs the tests under the control of Valgrind memcheck and helgrind tools. But then, if you want Valgrind to check the libabigail command line tools that are *forked* by some of the tests then type: make check-valgrind-recursive This one takes a long time. On my system for instance, it takes an hour. But then it checks *everything*. If you don't have that time, then "make check-valgrind" is enough, as the regression tests that use the libabigail *library* directly (as opposed to forking libabigail command line tools) will be verified. How tests are organized ----------------------- There are two kinds of regression tests. Those that use the libabigail *library* directly, and those that spawn one of the libabigail command line tools. Generally, both are usually made of a loop that churns through a set of input binaries to compare. Once the comparison is done, the resulting report is compared against a reference report that is provided. Test executable have names that starts with 'runtest*'. For instance, under /tests/ you can find tests named runtestdiffdwarf, runtestabidiff, etc... If a test executable is named /tests/runtestdiffdwarf, then its source code is tests/test-diff-dwarf.cc. Similarly, the source code of the test /tests/runtestabidiff is tests/test-abidiff.cc. The data provided for each test (for instance the input binaries to compare and the reference report that should result from the comparison) is to be found under tests/data. So data for the test runtestdiffdwarf is to be found under tests/data/test-diff-dwarf. Data for the test runtestabidiff is to be found under tests/data/test-abidiff.cc. So adding your own tests usually just amounts to adding the input right input into the right sub-directory of tests/data/. To do so, look at several tests/test-*.cc to see which one you'd like to add some input binaries to be compared in. Then once you know which tests/test-*.cc you'd like to extend, and if you added your input binaries and reference reports (maybe other things too) to the right sub-director of tests/data/, you just need to extend the array of input binaries/reference reports that the test walks to perform the comparisons. It's generally a global variable before the main() function of the test. In test-diff-dwarf.cc, for instance, the variable name is "in_out_specs". You just have to add a new entry to that array; that new entry contains the paths to your new input binaries and reference reports. Just read the code in there and use your brains. It should be straight forward. Ah, also, if you added new files for the tests, then the build system needs to be told that those files have to be added to the distribution tarball when we do "make dist" (or make distcheck). To do so, please make sure to add your new test input files to the tests/data/Makefile.am file, in the EXTRA_DIST variable. Look at how things are organized in that file, and please do things similarly. Sign your work ============== To facilitate tracking of who did what, we've adopted a "sign-off" procedure for patches based on the procedure used by the Linux kernel project. The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as a patch under an appropriate license. The rules are pretty simple: if you can certify the below: Developer's Certificate of Origin By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me, and I have the right to submit the contribution under the license indicated in, or otherwise designated as being applicable to, the file. (b) The contribution was provided directly to me by some other person who certified (a), and I have not modified it. (c) I understand and agree that the project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed. then you just add a line saying Signed-off-by: Random J Developer using your real name (sorry, no pseudonyms or anonymous contributions.) git commit --signoff will add such a Signed-off-by line at the end of the commit log message for you. Modifying the website ===================== The source code of the website of libabigail is stored in CVS (sigh, yeah, that is so old school). You can check out that web source code by doing: CVS_RSH=ssh cvs -z9 -d :ext:user@sourceware.org:/cvs/libabigail/ co htdocs where 'user' is your username on the sourceware system. Alternatively, you can check out the the web source code anonymously, if you don't have any user account on the sourceware system by doing: export CVSROOT=:pserver:anoncvs@cygwin.com:/cvs/libabigail cvs login (the CVS anonymous password to use is "anoncvs") cvs checkout htdocs Happy Hacking!