cvs commit: jakarta-alexandria/docs README.txt

[ni...@apache.org]

nicolaken    2003/03/28 00:37:46

  Added:       docs     README.txt
  Log:
  some docs
  
  Revision  Changes    Path
  1.1                  jakarta-alexandria/docs/README.txt
  
  Index: README.txt
  ===================================================================
  Javasrc Scalability Changes
  Overview
  
  I'll refer to the old version of javasrc as Javasrc 2000, and the new 
  version that I've been working on as Javasrc 2001.
  
  Javasrc 2000 is a great tool but its design restricts its scalability
  to a few thousand files. Because it processes all files in a single 
  pass, its scalability is limited to the number of symbol tables that 
  it can hold in memory simultaneously.
  
  Javasrc 2001 is meant to be used like javac. When you need to compile
  tens of thousands of files, you don't compile them in a single huge 
  javac invocation. Instead, you run javac once per source code 
  directory. If there are dependencies between directories, you first 
  compile the files in the least-dependent directory and then move up
  the directories in the dependency graph until you reach the files 
  in the most-dependent directory. Javac resolves references between 
  directories by selectively loading classes files that were generated 
  in previous invocations.
  
  Javasrc 2001 sacrifices convenience and speed for improved scalability.
  javasrc had to store the entire symbol table for every source file in
  memory simultaneously. The more files it processed, the more memory
  it consumed.
  
  Javasrc 2001 is broken into two separate programs that together behave 
  like a compiler and a linker. The first pass parses files and creates 
  the marked-up source code listings (the *_java.html files). For every 
  class that it parses, the first pass also writes a symbol table file 
  to the output directory. The second pass sweeps back through the 
  temporary files to create the cross-reference files (the *_java_ref.html 
  files).
  
  Usage
  
  You invoke the first pass like this:
  
  java -cp "JAVASRC/classes;JAVASRC/bin/antlr.jar" [-Drecurse=RECURSE] [-Dtitle=TITLE] -Doutdir=OUTDIR javasrc.app.Pass1 sourcedir1 [sourcedir2 ...]
  
  where JAVASRC is the directory where JAVASRCis installed, 
  RECURSE is "yes" or "no" (default is "no"), TITLE is the title of 
  your project, and OUTDIR is the directory where Javasrc writes its 
  output files.
  
  If you've used Javasrc 2000, this will all look familiar; the only 
  real difference is that whereas Javasrc 2000 would process all source 
  files in a single invocation, Javasrc 2001 is designed to process one 
  directory at a time. This isn't to say that it's impossible to process 
  more than one directory at a time, or that Javasrc 2001 won't recurse 
  to subdirectories -- you can still do all of that. But if you want to 
  process thousands of files, you're probably already using something 
  like Ant or Make to compile your files one directory at a time, and 
  in that case it should be easy to add Javasrc 2001 to your build 
  environment.
  
  Note that you always want to specify the same OUTDIR to pass1, 
  regardless of which package or directory your .java files are in.
  
  Once you've run everything through pass1, you need to run pass2 
  exactly once, like this:
  
  java -cp "$JAVASRC/classes;$JAVASRC/bin/antlr.jar -Doutdir=OUTDIR javasrc.app.Pass2
  
  Example
  
  Let's assume you have three directories -- A, B, and C, -- containing Java files. 
  Assume further that files in C refer to files in A and B; 
  files in B refer to files in A, and files in A refer to files in neither B nor C. 
  The dependency graph looks like this: C -> B -> A. You'll build a cross-reference like this:
  
  java -cp "JAVASRC/classes;JAVASRC/bin/antlr.jar" -D"My Project" -Doutdir=c:/project-javasrc javasrc.app.Pass1 A
  
  java -cp "JAVASRC/classes;JAVASRC/bin/antlr.jar" -D"My Project" -Doutdir=c:/project-javasrc javasrc.app.Pass1 B
  
  java -cp "JAVASRC/classes;JAVASRC/bin/antlr.jar" -D"My Project" -Doutdir=c:/project-javasrc javasrc.app.Pass1 C
  
  java -cp "$JAVASRC/classes;$JAVASRC/bin/antlr.jar -Doutdir=c:/project-javasrc javasrc.app.Pass2
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: alexandria-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: alexandria-dev-help@jakarta.apache.org