Source

doozer / docs / todo.txt

Full commit
- nasty hack in rgxscan.py. KeyError from threading.py.
- docs for functions exported from doozer module
- would be nice to be able to have tighter control over the environment -- strip out everything that isn't necessary
    - would need a list of variables that should always be there on each system
- system libraries should form part of a linker operation's signature
- each kit should provide a description of itself (without having to install it), for e.g. quickhelp
- support 'override' feature in flags map e.g. 'optimize-max' should override 'optimize', etc
- functions for copying files (using mtimes to check for the need)
    - single file
    - copying a tree
    - syncing a tree (removes files that shouldn't be there)

Future?
-------
- Is it possible/reasonable to have a feature that downloads/unpacks modules? 
    - Could subproject() be augmented to recognize zip files and URLs?!
- support for Objective-C
- support for D
- support Windows resource compiler
- native header scanners for GCC and Visual C++
- handle forced-includes
- precompiled headers
    - take name of header file
    - look in opt.includes for header
    - put precompiled version under builddir()/'pch' with correct relative path
    - add builddir()/'pch' to include paths while compiling
    - how is dependency analysis affected?
        - would adding the pch as a dependency to the object file be sufficient?

GCC
---
- shared libraries should record runtime libs as dependencies
- proper support for OS X frameworks
    - specified in opt.frameworks and opt.frameworkpaths
    - header scanner should use any frameworks found under opt.frameworkpaths and system framework dirs:
        - osx.sdkroot/System/Library/Frameworks
        - osx.sdkroot/Library/Frameworks
    - header resolution should also look inside a framework as headers can be found in:
        - XYZ.framework/Headers
        - XYZ.framework/PrivateHeaders
        - XYZ.framework/Frameworks/Other.framework/Headers
        - XYZ.framework/Frameworks/Other.framework/PrivateHeaders
    - #include <XYZ/header.h> can mean XYZ.framework/Headers/header.h, for example


Visual C++
----------
- can we support copy-runtime-libs in order to copy CRT dlls?


Other toolchains:
-----------------
- support for borland
- support for digital mars


Tests cases
-----------
Basics:
- static library
- shared library
- executable
- executable that links against one or more static libraries
- executable that links against one or more shared libraries
- touching a source file causes update of object file and library/executable
- touching a header file causes update of object file(s) and library/executable
- custom defines
- custom include paths
- abstract flags
    - some should be do-able, but others tricky e.g. optimization levels
    - may have to scan issued compiler command lines for flags
- targets and target suffixes
- subprojects
    - recursive should fail
- config includes
    - recursive should fail
- compiling .c files as C++
- compiling .cpp files as C

Slightly more advanced/tricky:
- executable that links against a dll that was itself linked against some dlls.
    - are dlls copied next to executable? Or is executable runnable?
- executable that is told to link against multiple copies of the same library:
    - copies should be weeded out
- executable that is given libraries in reverse order
    - as far as possible, linker command line should be adjusted to cope with arbitrary library order

Tool chain lookup:
- Finds Visual C++ directory
    - Including VS 2003
- Finds Windows SDKs
    - Can be used with all SDKs
- Finds MinGW install in default location
- Recognises gcc/g++ as MinGW/Cygwin/...
- setting win.version hides certain functions from Windows compilers

General issues:
- How to test Visual C++ on a machine without Visual C++ installed?
    - and so on for other tool chains
- How to test Visual C++ with different versions SDKs?
    - have to isolate code that finds Visual Studio and SDKs


Documentation
-------------

Goals:
- small and easy to distribute with projects
- portable, abstract
- general purpose scripting language needed
    - can fall back to Python if needed

Tutorial:
---------

Getting started:
- basic command line
- quick-help available
- contents of simple config file
- contents of a simple build script (creates executable)
- running the script
    - notice output folder name
    - notice sub-folders
    - delayed output
- specifying targets
    - full target name comes from script basename + target
    - multiple targets supported
    - clean
    - clean1
    - rebuild
    - rebuild1
    - last target chosen by default

- overriding variables on the command line
- verbose option
- buildroot
- displaying the available kit
- cwd, here

Writing build scripts
- target decorator
    - memoization and .force
- accessing variables in a build script
- builtin functions and variables
    - builddir()
    - cwd, here
    - cancel()
    - subproject()
        - memoization
- kit
    - created from 'kit' variable
    - passed to each target
    - kit.c and kit.cpp will contain stuff for building C and C++ programs
        - other languages may be added at some point e.g. D, asm, Objective C
    - opt()
        - passed to other functions, configures build steps
        - abstract flags mapping
            - iso, iso-c89, iso-c90, iso-c99, iso-c++98, iso-c++03, iso-c++03
            - no-rtti
            - no-exceptions
            - warn
            - warn-extra
            - warn-extreme
            - warn-as-error
            - warn-optimization-failure
            - debug
            - debug-stl
            - debug-stl-extra
            - debug-runtime-checks
            - debug-info-external
            - debug-info-internal
            - keep-asserts
            - optimize
            - optimize-max
            - optimize-size
            - optimize-vectorize
            - optimize-global
            - optimize-via-profile
            - mmx, sse, sse2, ..., avx, altivec
            - profile
            - gui
            - console
            - static-runtime
            - dynamic-runtime
            - default-symbols-hidden
            - default-symbols-visible
            - strip-symbols
            - stable-system-headers
            - stable-system-libs
            - unordered-libs
            - copy-runtime-libs
        - can add/remove items after abstract items have been converted
        - UniqueList is the default
            - ordering libraries
    - lib()
    - shlib()
    - obj(), objs()
    - exe()
    - installed()

Miscellaneous:
- cache
- distribution system


Reference:
----------

kit
- description of each
- variables for each
- abstract mappings for each


Hacking guide:
--------------
- getting source
- build.py
- DOOZER_USE_LOCAL_PACKAGE environment variable
- adding new kit
    - interfaces
    - installing it in toolchain
- distributing work