Re: Libification project (SoC)

"Luiz Fernando N. Capitulino" <lcapitulino@mandriva.com.br> wrote:

Excellent!
 

Yes. Removing all of these is not completely necessary in the first version; in fact I would recommened against it.

For example the active_cache variable and its related friends is referenced a lot. lt contains the index in memory. I think its perfectly OK to say that in the first iteration of a public libgit.a that the process may only use one index at a time, if it can even use the index at all (see below). But if you eventually got around to even helping the index parts of "the Git library", that would certainly be appreciated!

On the other hand, many of the variables declared in environment.c are repository specific configuration variables. These probably should be abstracted into some sort of wrapper, so that multiple repositories can be accessed from within the same process. Why? a future mod_perl running gitweb.cgi accessing repositories through libgit.a and Perl bindings of course!

But static variable removal is low on the priority list for this project I think. Our more important issues are related to some of the other items.

malloc is a huge problem in the Git code today. Almost all of our malloc calls are actually through the xmalloc wrapper. All xmalloc callers assume xmalloc will *never* fail. This makes it, uh, interesting. ;-)

Although one could argue that being unable to malloc needed memory probably means you're toast, so die()'ing is good.

But other areas die when they get given a bad SHA-1 (for example). If the library caller can supply that (possibly bad) SHA-1 to an API function, that's just mean to die out. ;-)

Yes, of course. But most functions (at least those that should be made public) probably already do check their arguments. Some return an error code back to their caller; others die() and abort the current process. And there are probably a few that don't check their arguments enough. But I think input parameter checking is probably going to be a relatively small task here.

Although sometimes the input checking is done in the program that calls the function, and not the function itself. So that might need to be refactored in a few spots.

Yes; very important for the library to be of any use to anyone else.

Of the public API, yes. Our current test suite covers some of that code that we want to make public, but does so through programs that call those functions. We would want unit tests to verify the public API conforms to the expectations of the unit test's writer. ;-)

Yes.  But which functions shall we expose?  ;-)

See below for functionality I'm thinking about; others may have
different ideas.
 
      o Build system issues

You missed this, but I think its an important consideration. Our current libgit.a is a static library that has a relatively large number of symbols its modules are exporting. These symbol names aren't namespace-ized (e.g. git_* prefix) so we wouldn't want to just offer this library up in its current form.

Some of those symbols would get name changes (as you suggest above), but others might not (e.g. the active_cache that I suggest further above). These modules might need to be moved out of libgit.a and moved into say a new libgitprivate.a, that our own code can link against, but that isn't offered to the public as a stable API.

      o Public header definition

Whatever we expose, we will need to draft a public "git.h" (or somesuch) that callers can rely upon. It will need to be fairly stable, and handle revisions as new features get added. E.g. version testing support like the zlib and cURL library have, and that we rely upon in Git to do feature checks. ;-)

I'd like to see enough API support that gitweb.cgi could:

 * get the most recent commit date of all refs in all projects
   (the toplevel project index page);
 * get a shortlog for the main summary page of a project;
 * get the full content of a single commit;
 * get the "raw" diff (paths that changed) for two commits;

There's a thousand other things that gitweb.cgi would still need to fully avoid forking Git processes. But that's a really good start, and is probably going to be a decent chunk of work. Especially to create high-quality patches that pass our standards review. ;-)

In some cases much of the above is already "internally public"; meaning we already treat parts of that code as a library and invoke them from within processes to get work done. Much of this project is about improving the interfaces and behavior enough to make those existing APIs truely public.

See refs.h, diff.h, revision.h, commit.h...
 

No, I don't see that as a problem at all. We have some Perl experts on the mailing list who would like to see Perl bindings. Some of the Perl binding is pure C code, and some if it is this weird Perl macro language... so I expect those Perl experts to come out of the woodwork and help the community to create a prototype set of bindings. There's also Ruby and Python interests around, so we may see bindings for those too. ;-)

that can support a gitweb type of application would be great. It shows the library works as intended, is useful, and can be continued to be built upon. That's a pretty successful project in my mind.