Details
-
Improvement
-
Status: Closed
-
Major
-
Resolution: Fixed
-
None
-
None
-
None
-
Moderate
Description
That's pretty right and informative instruction which helps to build DRLVM w/ classlib for debugging.
Still there are set of points which may be improved (at least they made me confused & pushed to think...).
======================================================
1. "Windows requirements":
It contains: Microsoft Visual Studio.NET 2003 or higher
In fact "of higher" does not work, so this "of higher" should be removed.
======================================================
2. "Additional software"...
Ok, it is readable like "Additional software for Linux". It is recommended to say explicitly that this "Additional software" is required for both Windows and Linux.
======================================================
3. "Note about SVN"...
It says that "The PATH environment variable must include the location of SVN tool set". In fact it is true for all tools in requirement - like ant or Java SE 5 JDK.
So this phrase is confusing. It should be either removed or extending by rest of tools - all executables must be in PATH.
======================================================
4. "Note about SVN"...
We need to mention here the "work from behind the firewall". Like:
If you are working from behind a firewall, you may need to configure the proxy setting for 'ant' and 'svn' tools. Use ANT_OPTS environment variable for 'ant'. Setting proxy for 'svn' depends on version of this tool you use. For example, edit ~/.subversion/servers file for console version of 'svn'.
Also the same kind of note should be removed from "Building the Class Library" section.
======================================================
5. "Note about SVN"...
Ok, it is about "Run SVN manually at least once prior to build" ... It does not make too much sense - if you did not run 'svn' then you do not have sources - nothing to build. So, the note may be rephrased by adding the prefix phase like: "if you get sources to be build w/o running svn command then you need to ...".
======================================================
6. "Alternatively, you can download" ...
It belong to #2 above "Additional software" (I believe). So:
- need to say explicitly that "Additional resources can be obtains during the build like written in later section. Alternatively, you can download these resources ..."
- also the notes about "PATH", "proxy" and "run svn prior to build" should be moved out of "Additional software" section.
======================================================
7. Additional note may help like:
Note: the build is evolving. So if you encountered issue please double check dev-list - they issue may be known already, the solution may be proposed (like recently happened with missed MSVCR71.dll).
======================================================
8. In "Populating the VM and ClassLibrary Source Trees"
It may worth separating a note about "updating sources" ("Any time going forward, you can bring any directory to current SVN...") to separate chapter (same to "Populating the VM and ClassLibrary Source Trees"). Like "Updating the VM and ClassLibrary Source Trees".
======================================================
9. Cosmetic note for all platform specific command example.
In "Prerequisites" ones used bold Windows (going first) and bold Linux (going second) to give platform specific requirements.
It may worth following same style while giving platform specific commands samples.
Like instead of:
unzip <path_to_vm_zip> -d ../.. (on Windows)
it may be
<b>Windows: </b>
unzip <path_to_vm_zip> -d ../..
======================================================
10. Platform independent command
Ok, it may worth saying somewhere near the first command example that platform independent command are given in Linux style with bash default prompt ($).
In fact this rule is true for most of examples in instruction.
Also it makes sense to unite:
$cd working_vm
$cd build
to
$cd working_vm/build
======================================================
11. Building steps
"Building DRLVM" sub-section contains several steps which are emphasized by code samples only.
Ok, it is proposed to define each step as short bolded action summary. Like:
<b>Enter build directory</b>: when the class library is built ...
<b>Edit drlvm.properties</b>: First of all, tell the DRLVM ...
And so on...
======================================================
12. Note about "drlvm.properties".
The text around this property says about location of classlib to be used for drlvm build. In fact this file define also another property which required for later build steps given in instruction.
It is proposed to add the note about "deploy.canonical.flag = true" saying that w/o this property setting to true the build does not create directory "deploy/jre/bin" which is referred bellow.
======================================================
13. Complier options blue table
Would be helpful to see the (compiler) options defaults.
Also need to know the defaults for debug/release options and what way to switch between them.
======================================================
14. Need a note "build" step (for classlib)
I failed to build classlib after sources update in 80% of cases w/o cleaning previous build. So the note is important:
Note: if you fail to rebuild classlib after "svn update" command, clean previous build results:
$ant clean
======================================================
15. Contradiction in "Using" / "Running" section.
Ok, first one says JAVA_HOME must point to deploy/jre/bin to run DRLVM, second one says it may be unset also.
======================================================
16. common note: worth specify gcc compiler version range
gcc compiler
Next iteration is possible.
Thanks
Vladimir