[GSoC] "Modularize Automake" Final Report

[Matthias Paulmier]

Hello everyone,

As you may know, I worked on Automake this summer as part of the GSoC.
Here is my final report on this project.  I hope you will find it
informative.

                   __________________________________

                    [GSOC] REFACTORING: FINAL REPORT
                   __________________________________


1 Introduction
==============

  As the program comes to an end, it is time to report on the work that
  has been done during this period.  This is my final report for the
  GSoC project "Modularize Automake to improve the test-suite".  In this
  report, I will attempt to explain the work that has been done during
  this summer.  As I expected with this project, there was a lot of work
  to do and there is still a fair bit left to do to totally complete the
  project.

  The work I have done can be found on the [Automake git repo] on the
  branch [experimental/gsoc/refactoring].  The commits I made go from
  `be2458dd8` to `2d7d3fd31`.


[Automake git repo] http://git.savannah.gnu.org/cgit/automake.git

[experimental/gsoc/refactoring]
http://git.savannah.gnu.org/cgit/automake.git/log/?h=experimental/gsoc/refactoring


2 The Exporter module
=====================

  This is probably not a very crucial point but we now have a
  homogeneous usage of the Exporter module.  Before that we had
  different uses depending on the module.  Some of them used the
  following:
  ,----
  | use Exporter;
  | use vars qw (@ISA @EXPORT);
  | @ISA = qw (Exporter);
  | @EXPORT = qw ([...]);
  `----

  While others used:
  ,----
  | require Exporter;
  | [...]
  `----

  All of those modules declared themselves as sub classes of the
  Exporter module.  I didn't know which of `use' or `require' provided
  the best option or if there was a difference in terms of performance
  at all.  So I went and asked more experienced Perl devs about that and
  was advised to use the following form:
  ,----
  | use Exporter 'import';
  | use vars qw (@EXPORT);
  | @EXPORT = qw ([...]);
  `----

  So now, none of our modules inherit from the Exporter class and they
  all use the same form.  What could be investigated now is whether
  address@hidden' is really what we want or rather use the address@hidden'
  variable and let the "clients" (even though here we only have
  `automake' and `aclocal') choose which function/method they need.  In
  theory, the second option seems to be a more reasonable approach,
  however I didn't investigate this option much.


3 New modules
=============

  Some new modules have been created during this period.  Of course,
  there hasn't been new features added, but the code is now better
  organized and functions are grouped coherently together.

  The following modules have been created:

   Module name      Role
  
---------------------------------------------------------------------------------
   CondStack        Checks on the conditional stack
   ConfVars         Define new configure variables
   Errors           Print errors for ac and am files
   File             Read the contents of a file
   Global           Holds global variable/constant declarations
   HandleConfigure  Handle configure files from automake's point of view
   LangHandling     Helper functions for defining different languages
   Requires         Functions for requiring files in 'Makefile.am's
   Standards        Functions for checking the conformity with GNU/GNITS 
standards
   Texi             Functions for handling texinfo files
   Utils            Miscellaneous functions
   VarAppend        Helper functions for the Variable module

  Although I said in the previous report that the goal is to move all
  the functions away from `bin/automake[.in]', I think letting some of
  them in it might better alternative (maybe Utils.pm).  For instance
  `usage', `version' and `parse_arguments' seem to fit in the main
  script as they are strongly bound to it.


4 Tests
=======

  I have added some tests under the `t/pm/' directory as part of the
  testsuite.  I still need to work on my testing skills as I have some
  issues coming up with good tests for non trivial functions.

  I have also removed a "hack" in the test suite for which I am pretty
  pleased.  Some Perl tests are testing that a misuse of the library
  effectively creates a fatal error.  So far, we just had each of those
  test cases in separate files that were expected to fail as they ended
  in a fatal error.  I have been able to overcome this problem with the
  Perl `eval' function that is able to capture the errors of a block of
  code without interrupting the program.  Now Perl tests are properly
  grouped by module (some modules are tested twice: once without the use
  of the `threads' lib and once with it) and all PASS as expected.


5 What more could be done
=========================

5.1 Tests
~~~~~~~~~

  I am not an expert on tests but I am sure we could come up with more
  test cases for certain modules.  For example, I tried testing the
  CondStack module which takes care of verifying that the successive
  calls to `if', `else' and `endif' are in the correct order.
  Unfortunately I later realized that my tests and assumptions on how
  the module worked were somewhat wrong and I ended up removing the
  tests from the repo as I couldn't come up with better tests.


5.2 Documentation
~~~~~~~~~~~~~~~~~

  Although all the methods are properly documented, they don't all use
  the same documentation conventions.  Some use the [pod] format while
  others use comments as documentation.


[pod] http://perldoc.perl.org/perlglossary.html#pod


5.3 More modules
~~~~~~~~~~~~~~~~

  There are still some functions in the main script that should be put
  in modules.  As easy as it is to create new modules and dump those
  functions inside them, my goal was to create modules with good
  cohesion and keep coupling low.  So it took a lot of time to come up
  with modules or integrate functions to existing ones.  If you followed
  the repo, you may have noticed that I "reset" the branch somewhat
  regularly.  That's often because I realized, after creating some
  modules, that they were poorly made or that their methods belonged
  elsewhere.  Even though the work seemed (and was mostly) repetitive, I
  had to think a lot about that and it slowed me down quite a lot in
  this task.


6 Communication
===============

  At the beginning of the program, I said that I would communicate about
  my progress regularly on this mailing list.  As you may have noticed,
  I didn't really do that.  This is because we changed the way we were
  originally supposed to communicate with Mathieu.  We were originally
  going to have an non formal vocal meeting every week and I would write
  a report to the list every time it was necessary.  After a few
  meetings, we decided that we would change that to a weekly written
  report to him.  This was better for me for two reasons:
  - No time constraint (I could write the report whenever I want during
    the week).
  - I could write it in french, which makes it faster for me.


7 Conclusion
============

  This summer has overall been a great experience for me as I have
  learned a lot about Perl and tests in general.  This was a big
  challenge for me as I have never worked on such a large code base (it
  may not be much for others but it was quite a significant one for me).
  As we have seen above, the project still needs some work as I have
  said previously.

  As you may know if you follow this list, Mathieu is stepping down as
  maintainer of Automake.  The code produced this summer will therefore
  not be integrated into the project until someone is taking on that
  role and is willing to review the changes.

  I am not aware of anyone taking on the role of maintainer of Automake
  so far but, when this person is there, I am willing to work with them
  to be able to integrate my code into Automake as well as improving or
  expanding it (while I will not be as available as this summer i am
  still willing to contribute).  Be it partially or in its entirety.  I
  think some parts could be very interesting for the project.
  Especially the fix of the Perl `XFAIL' tests and the use of the
  `Export' module inside Automake.


--
Matthias Paulmier