This is a list of issues which should be addressed in the Jam-based build
system.

H - High Prioriy (important showstopper)
M - Medium Priority
L - Low Priority (only minor function loss)
W - Wishlist (the build also works without this feature)
* - Completed

[H] msvcgen.jam: Provide rules to copy the generated files back to the source
    tree upon explicit request so that they can be committed to the CVS
    respository if desired.
[H] We need a rule for making platform-specific shared libraries which are not
    CS plugins. This is needed, for instance, by the pythmod, perl5mod, and
    javamod targets which create pure scripting extension modules (shared
    libraries). It might be possible to hijack the existing Plugin rule to do
    this, or it might make more sense to create a distinct rule. Presently,
    these modules are created with a bunch of custom Jam code which involves
    a lot of copy/paste, is difficult to maintain, and is fragile because it
    relies upon internal knowledge of the Plugin rule and the low-level
    platform-specific SystemFoo rules invoked by the Plugin rule.

[M] Figure out how to create MSVC project files for the pure Python and pure
    Perl extension modules.
[M] Write complete documentation about the Jam build system for the CS user
    manual.
[M] Write a tutorial (maybe we could just link to the text in the RoboRun
    project?).  Another interesting topic would be integrating Crystal Space
    with other build systems like Automake or Ant.
[M] Re-work the provided m4 scripts to provide functionality like
    CS_CHECK_HOST.  Would be also nice to extract more of the detection scripts
    in CS (perl, nasm, problematic cflags?)
[M] Add a generic "Defines" rule which works similar to the CFlags rule, but is
    specifically geared for specifying preprocessor defines. Special-case tools
    may take advantage of this extra knowledge. For example, msvcgen can fill
    in the "AdditionalDefines" key in project files. Remove the MsvcDefine rule
    which presently handles this case for msvcgen. Note that the new Defines
    rule will require some care since some preprocessor definitions are
    suitable in all cases, whereas others might be suitable for only certain
    platforms, and still others might apply only during project file
    generation. The rule should probably accept a third argument which provides
    fine-grained control over the scope or disposition of the invocation.

[L] The UnitTest rule needs to be re-engineered so that it no longer provides
    the capability of consolidating unittests from unrelated directories into a
    monolithic test program (when the user invokes one of the directory-based
    `check' targets). Although this feature has a high "coolness" factor,
    creating a monolithic test program can result in symbolic conflicts. For
    instance, if the simple1, simple2, and simpmap programs all define a class
    named `Simple', then trying to combine all of those objects into a
    monolithic test program would fail. Therefore, the test programs need to
    remain separate, however it would be nice to consolidate the results of the
    invocations of the individual test programs so that the output can be
    viewed all together, and also, the failure of a test program should not
    prevent remaining test programs from running.
[L] The UnitTest framework needs to be thought-out more thoroughly with regards
    to applications and plugins. One problem with trying to link object files
    from an application or plugin into a unit test program is that there will
    be multiple main() functions (one from the application or plugin itself and
    one from the unit test driver program). How should this situation be
    handled? Should the client be responsible for moving the application's or
    plugin's main() function into a separate compilation unit which does not
    get linked into the unit test program?  Should the UnitTest framework
    attempt somehow to mask the application's or plugin's main() by #defining
    it to something other and then compiling that particular source a second
    time specifically for inclusion in the unit test program? Once this issue
    is resolved, re-enable invocations of UnitTest in the Application and
    Plugin rules.
[L] The 'clean' targets for msvcgen error out when Jam's -j option is used to
    run multiple build commands in parallel. If msvcgen has run and needs
    cleaning at 'clean' time, Jam will attempt to invoke separate commands "rm
    -rf ./out/mk/msvc" and "rm -rf ./out/mk/msvc ./out/msvcgen/build7
    ./out/msvcgen/temp7" in parallel, and the command which cleans only
    ./out/mk/msvc will fail with an "./out/mk/msvc not found" error. This
    problem does not occur when commands are run serially.
[L] Jorrit reports that with the command "jam -sMODE=profile walktest_static",
    dynavis/debug/static/dynavis.o gets compiled twice. (Is this still valid?
    Static plugin support has changed a good deal since this was reported
    originally.)
[L] msvcgen.jam: Consider overhauling the "configuration" file handling rule so
    that it associates configuration files with built targets.  This will allow
    the generated projects to reference configuration files.  Rather than the
    present InstallConfig rule, we might want a ConfigFile:<target>:<configs>
    rule.  (The GNU make-based msvcgen does this.)  Note that this is just a
    convenience for the user of the project file; the project file itself will
    function correctly without this information.
[L] msvcgen.jam: Provide a generic Resources() rule which allows specification
    of additional textual resources for inclusion in generated projects.  (The
    GNU make-based msvcgen does this.)  Note that this is just a convenience
    for the user of the project file; the project file itself will function
    correctly without this information.
[L] msvcgen.jam: When modules reference sources or headers outside of the local
    source directory via some number of ".."'s, these resources appear as
    "../../foo/bar/../../this/module" in the generated project file.
[W] Add support to create Microsoft CHM format documentation packages.
[W] Finish the tool for extracting the documentation from the rules files.
[W] Create templates for some IDEs.  Generating a template for KDevelop3.x is
    very easy, in theory, as it comes with a great plugin architecture allowing
    for custom build plugins.  However, there are only standard plugins for
    make, ant, and qmake.  We'd have to write a custom Jam plugin first; there
    is no way to have a "standard" plugin where you specify just some commands
    for building/updating.  Seems we have a similar situation in Anjuta.
    Creating project files would be easy but they also rely on make.  Anjuta2
    seems to be better, and provides support for custom commands being run for
    building, however the code seems to have a bug at the moment and always
    adds -k to the command-line.  :-(
[W] It would be nice to have the configure files regenerated and execute if the
    configure.ac file has changed.  Unfortunately it is not possible to force
    jam to re-read its configuration files, so this isn't 100% possible.  Would
    it be possible to somehow recreate the configure files and then exit Jam
    with a message telling that you should rerun configure, or at least emit a
    big warning?

[*] Eliminate the need for the documentation-building shell scripts; the ones
    which copy image files from docs/texinfo/* into the build directory.  Jam
    is sufficiently expressive that it should be able to handle the
    image-copying and other functionality without depending upon these external
    tools.
[*] The Texi2Info, Texi2PS, and Texi2PDF rules needs to clean up the "image"
    files (.jpg, .png, .gif, .txt, etc.) which are copied from the source
    directory to the build directory.  These files are fully incorporated into
    the generated documentation files as part of the conversion, and are not
    needed after conversion has completed.
[*] The Texi2DVI, Texi2PS, and Texi2PDF rules need to be augmented to maintain
    the TeX .log so that it can be reviewed for problems by the user.  Also, it
    might be wise to scan the file for common problems, such as error messages
    (denoted by "!") and warnings (such as the common 'hbox' warning) and
    present those messages to the user.
[*] The dvi, ps, pdf documentation rules incorrectly name the resulting file
    cs-unix.{dvi,ps,pdf} rather than crystalspace.{dvi,ps,pdf}.
[*] The info rule incorrectly names the resulting file crystal.info, rather
    than crystalspace.info.
[*] There are no rules for building the pure Perl5 module yet (only the Perl5
    plugin works).
[*] The csjava shared library gets the wrong file extension (.csplugin) on
    MacOS/X. We need to determine the correct file extension expected by Java
    and use that. (For instance, the CS configure script gleans this sort of
    information for Python and Perl in order to avoid this same problem.)
[*] Add a Jamfile for cscript/csjava.
[*] msvcgen.jam: The overriding LinkWith rule is not properly resolving the
    library dependencies for a target.  For instance, if "LibDepends D : A B C"
    has been invoked, then all generated project files which depend upon D
    should also automatically depend upon A, B, and C, but this is not
    happening for some reason (presumably due to a bug in the code).
[*] Upgrade jamtemplate/createproject.sh so that it can optionally set up
    msvcgen support (6 and/or 7) for the newly created project.
[*] msvcgen.jam: Generalize so that external projects can take advantage of
    this facility.  For instance, stop assuming that "../.." is always suitable
    for reaching the root of the project tree from the location of the project
    files; and stop assuming that project files always reside at
    $(TOP)/mk/visual#, and that templates reside at
    $(TOP)/mk/msvcgen/template#.
[*] msvcgen.jam: Eliminate dependency upon external scripts for merging .rc
    files and munging the content of ICON resource paths (this is highly ugly
    and prevents generic use by external projects).
[*] msvcgen.jam: Update to respect the new ApplicationIconDefault and
    ApplicationIcon rules.
[*] Introduce a new rule named Description and change all invocations of the
    Help rule (except the ones using the "verbatim" option) to invocations of
    the Description rule throughout the project.  Next, remove the "verbatim"
    option from the Help rule and make the Help rule _always_ treat its
    argument as verbatim. Also eliminate the anomaly where Help is hard-coded
    to prepend "Build the" to the incoming text.  Then, augment the
    Application, Library, Plugin, and ShellScript rules to invoke Help
    automatically with the text "Build the $(description)".  Finally, augment
    msvcgen.jam and win32.jam to utilize the target's decription string (as
    collected by the Description rule) rather than the help string (which is
    not necessarily appropriate as a module's description).
[*] There are no rules for building the pure Python module yet (only the Python
    plugin works).
[*] Doxygen rule causes warning of the sort on modern Unix platforms:
      Copy ./out/docs/html/api
      rm: cannot remove `./out/docs/html/api': Is a directory
[*] The `jobber' script on SourceForge should use jam instead of make.
[*] msvcgen.jam: The command line for creating a project and workspace files
    frequently overflows Jam's command-line length limit, causing it to abort
    rudely.  This happens easily, even with moderately sized projects, such as
    csutil, and workspaces, such as wkstypical, when $(TOP) and $(BUILDTOP) are
    somewhat lengthy pathnames.  When they are "C:\CS", or "/home/foo/CS", then
    the resulting invocations of msvcgen.pl are sufficiently small for Jam's
    limited command-line length, but anything beyond those simple, short
    pathnames results in frequent failure.
[*] msvcgen.jam: Add support to create multiple, customizable workspaces rather
    than always creating only wksall.  Obvious examples of workspaces are the
    ones presently created by the GNU make system: wksall, wkstypical,
    wkswalkall, wksnewrenderer.  This task is particularly problematic since
    creation of the wksnewrenderer target is entirely crippled by the fact that
    USE_NEW_RENDERER must be "no" in order to create the other workspaces, but
    "yes" to create this one. A different set of Jamfiles is loaded depending
    upon this setting, thus making it extremely difficult to get the proper set
    of module definitions.
[*] msvcgen.jam: There should be some way to indicate that project files should
    not be generated for certain applications, plugins, and libraries.  This
    could be done either via a monolithic list or on a module-by-module basis
    in each module's Jamfile.  (What are the relative merits of each approach?)
    Obvious examples for which MSVC project files should not be created are
    those modules which are specific to Unix and MacOS/X. "static" variations
    of targets are also very good candidates for exclusion.  (Be sure to
    exclude walktest_static.)
[*] msvcgen.jam: There should be some way to indicate that project files
    _should_ be generated for modules which are not normally included by a
    given configuration.  For instance, we might want to create a project file
    for the PNG loader even if the local machine does not have libpng
    installed.  Much more difficult, and important, is that we need to build
    project files for all of the new-renderer modules for the wksall and
    wksnewrenderer workspaces even when the project is configured for the old
    renderer. This is difficult because those Jamfiles will not even be
    included. We can not simply set USE_NEW_RENDERER=yes, because that will
    cause the old renderer modules to be omitted from wksall and the other
    workspaces.
[*] msvcgen.jam: Eliminate the ugly mk/msvcgen/msvcgen.sh.  Instead, it should
    be possible to run the entire process using the normal Jamconfig created by
    the configuration process and by simply invoking the desired targets
    (msvcgen, msvcgen6, msvcgen7).
[*] msvcgen.jam: Auto-generated MSVC project files should be generated into the
    build directory rather than the source tree, since the source tree might be
    read-only or shared.
[*] msvcgen.jam: When PERL5.AVAILABLE is "yes", Jam reports that it doesn't
    know how to locate or create <grist>csperlxs.c.
[*] When Bison and Flex are installed, the generated MSVC project file for AWS
    incorrectly mentions skinlex.ll and skinpars.yy, rather than skinlex.cpp
    and skinpars.cpp from the source directory.
[*] Auto-generated Swig files should be generated into the build directory
    rather than the source tree, since the source tree might be read-only or
    shared.  We should provide rules to copy the generated files back to the
    source tree upon explicit request so that they can be committed to the CVS
    respository if desired.
[*] Auto-generated Bison & Flex files should be generated into the build
    directory rather than the source tree, since the source tree might be
    read-only or shared.  We should provide rules to copy the generated files
    back to the source tree upon explicit request so that they can be committed
    to the CVS respository if desired.
[*] The MSVC-generated project file for csutil is missing all of the sources
    (and headers) from the cssys directory.
[*] Make handling of files in subdirs more robust (this is a about handling
    files for a single target): It should be possible to reference files in
    parent subdirs (i.e. ../bla/blup.cpp). Also it should be possible to have
    several files with same name in different subdirs.
[*] Improve handling of .rc files on Win32. Jam should know about them and you
    should be able to specify them like normal source files. (Caveats:
    mingw/cygwin only allow one .rc file per plugin/application, creating a
    correct version resource file is hard when doing it purely in Jam, but I
    don't want to rely on external shell scripts.)
[*] External projects on Win32 and MacOS/X shouldn't fail. The problem here is
    that the shell scripts in libs/csutil/win32 and libs/csutil/macosx aren't
    present in external projects. Should we collect scripts which are used by
    the build system or should we try to avoid these in the Jam build (these
    two problems can probably be solved by improving the Jam rules).
[*] MacOS/X rules should be aware of the structure of an application wrapper
    instead of using external shell scripts for generating them.  We also
    probably want some rules to insert additional stuff into the application
    wrappers.
[*] Re-work static plugin linking: This should not be an independent `mode',
    and the intelligence should not be put globally into the Application and
    Plugin rules.  Rather the Plugin rules should create a second target where
    they compile into a static library instead of a dynamic plugin.  For
    linking a static application you should use a second rule where you have to
    specify which plugins you want to have linked into the application.
[*] CS is using -fvtable-thunks flag on Win32 with gcc 2.x on MSYS.  This makes
    CS libraries incompatible with other applications.  Someone should check if
    we really need -fvtable-thunks in general or if we could specify it for the
    `ddraw' plugin only.  (Eric says: Checking if -fvtable-thunks is needed is
    the responsibility of the CS configure script, and indeed it has performed
    this check for quite a long time now.  The problem seems to be that this
    flag was hard-coded into win32.jam, despite the fact that the configure
    script provided correct information.)
