Re: CHANGELOG and documentation

[Bryce McKinlay <bryce at albatross dot co dot nz>]

Matt Welsh wrote:

> As it is now gcj's a real "black box" until you've spent some time playing with
it!

I agree that something of a user manual is needed eventually, certainly in time
for the next release. I imagine that it would be written in Docbook or some
similar XML/SGML based format and would supersede most of the existing html
documentation fragments on the sourceware site. Here's a draft toc I wrote up
indicating the sort of things that might go into it:

gcj/libgcj: User and developer guide
====================================

overview of the gcj environment

  supported APIs
  missing features
  differences with traditional VM environments
    - binary compatibility rules
  performance indications

installation guide

  overview
  supported platforms
  the compiler (gcc)
    - "configure" options
  the runtime library (libgcj)
    - "configure" options [threads, gc, sjlj/exceptions, interpreter]

using the gcj compiler

  compiling java source
  building a shared library
  specifying java system properties
  list of command line options
  examples

garbage collection: boehm-gc

  configuring heap size parameters

the bytecode interpreter

  overview
  gij, command syntax etc

API notes

  Dynamic class loading:
    Class.forName()
    Runtime.loadLibrary()
  etc

Debugging & Profiling

Compiled Naked Interface (CNI)
  (this would include Per's existing CNI docbook stuff)
  examples

Hacking guide

  how to port the threads/file/signal layer, from existing htdocs
  various "how it works" information