Simplify Waf's API

Disclaimer: i have only limited experience so far with waf, but i want to attempt to port mesa gallium3d's new scons build system over to waf, in order to confirm it's viability. since documentation is scarce,i might have gotten it wrong, but then a reply here would be a good start to document this feature

• set build- and sourcedir to sensible defaults if not set
• in waf script declare sub-projects at a central place(in init(), maybe ?), pulling in options, configurations and sources automatically into the top level/next higher level wscript.
• please follow the CapWords? style convention for the API(createObj() instead of create_obj()), afterall it's python's very own preferred style. faster to type, most commonly used style, easier on the eyes(ok, that last one is subjective)
• use full names for for API: Build.createObject() instead of bld.create_obj()-easier to read and to remember

Please simplify the DistTarball? API

Here is some proposed sample usage:

def dist():
    import hashlib
    from Scripting import DistTarball, DistGzipTarball, DistBzip2Tarball   
 
    # Snapshot adds the date to the cut release tarball.
    gz_tarball = DistGzipTarball(APPNAME, VERSION, snapshot=True)
    gz_md5_digest = gz_tarball.digest(hash=hashlib.md5())   # => '12e3fc...'
    gz_sha1_digest = gz_tarball.digest(hash=hashlib.sha1()) # => 'e96fa7...'
    
    bz2_tarball = DistBzip2Tarball(APPNAME, VERSION, snapshot=False)
    bz2_md5_digest = bz2_tarball.digest(hash=hashlib.md5())
    bz2_sha1_digest = bz2_tarball.digest(hash=hashlib.sha1())

    # Output checksums...
    print bz2_sha1_digest, bz2_tarball.name
    ...

    # OO.
    isinstance(tarball, file) # => True
    isinstance(tarball, DistTarball) => True
    isinstance(tarball, DistGzipTarball) => True
    isinstance(tarball, DistBzip2Tarball) => False

as against the current

def dist():
    import md5
    from Scripting import DistTarball
    (f, filename) = DistTarball(APPNAME, VERSION)
    f = file(filename,'rb')
    m = md5.md5()
    readBytes = 100000
    while (readBytes):
        readString = f.read(readBytes)
        m.update(readString)
        readBytes = len(readString)
    f.close()
    print filename, m.hexdigest()
    sys.exit(0)

The current pattern will unnecessarily get repeated in future projects using Waf, which means more people will make mistakes and these mistakes won't be in one place to be fixed. By providing a method such as "digest(crypto_service)" you are allowing people to choose whether they want to generate a release digest.

I wish there have a wiki page for help Makefile user learning the waf. And also put a simple makefile.<platform> in demo/make directory. That let makefile user could quick understand how to do such thing in waf. I could provide a sample makefile for linux+gcc and solaris+gcc.

words_with_underscores is PEP-8 and the preferred Python style.

following davvid's comment (which was in reply to maxim.mueller), waf mostly follows the python naming convention (expect for package names, which normally should be lowercase)

wildcards in source Waf provide two utility methods in the Node class to find sources that match (or don't match) some patterns: Node.find_iter and Node.ant_glob. The TaskGen? class also has a find_sources_in_dirs method, but be aware that it doesn't recurse into subdirectories.