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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
