harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Vladimir Beliaev (JIRA)" <j...@apache.org>
Subject [jira] Created: (HARMONY-2318) [doc] clarification for Getting Started For Contributors
Date Fri, 24 Nov 2006 15:55:02 GMT
[doc] clarification for Getting Started For Contributors
--------------------------------------------------------

                 Key: HARMONY-2318
                 URL: http://issues.apache.org/jira/browse/HARMONY-2318
             Project: Harmony
          Issue Type: Improvement
          Components: Website/Documentation
            Reporter: Vladimir Beliaev


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


-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

        

Mime
View raw message