Replace BUILDING.txt with a simlified up-to-date BUILDING.html

• Key: DERBY-3985
• Type: Improvement
• Status: Resolved
• Resolution: Fixed
• Priority: Major
• Assignee: Rick Hillegas
• Reporter: Rick Hillegas
• Component/s: Build tools
• Affects Version/s: 10.5.1.1
• Fix Version/s: 10.5.1.1

Description

At this point, BUILDING.txt contains a number of mis-statements. It is structured in a way which makes the Derby build look complicated and intimidating. The build instructions need to be thoroughly overhauled and divided into two main sections:

1) The simple build instructions for people who are new to the community. This will be a build with few pre-requisites which just works out of the box.

2) Trickier build instructions for people who want compile-time checks for the different platforms which Derby supports.

While we're at it, I suggest that the revised instructions live in an html file rather than a flat text file. I think this will result in a document that is more readable and easier to navigate.

Comments

[Rick Hillegas]

Attaching derby-3985-01-aa-simplerBuildInstructions.diff. This replaces BUILDING.txt with a web page, BUILDING.html, which contains simplified instructions for building Derby. Note that this patch should not be committed until DERBY-3984 is done.


Touches the following files:

A BUILDING.html
D BUILDING.txt

Replaces BUILDING.txt with BUILDING.html.


M java/build/org/apache/derbyPreBuild/PropertySetter.java
M java/testing/org/apache/derbyTesting/functionTests/tests/jdbc4/README.html
M java/testing/org/apache/derbyTesting/functionTests/tests/junitTests/compatibility/testScript.xml

Replaces references to BUILDING.txt with references to BUILDING.html.

[Knut Anders Hatlen]

The description looks fine to me. Some minor comments:

-

[Knut Anders Hatlen]

The description looks fine to me. Some small issues:

- There are some problems with the HTML (for instance end tags with no matching opening tag). You may want to pass it through an HTML validator (for instance http://validator.w3.org).

- Should the document be made self-contained? Now it embeds images from https://issues.apache.org. It would be good if one didn't need a network connection to see all the contents (and are the URLs on issues.apache.org stable?).

- Should the advanced build section mention the j14lib and j15lib properties? I think they still work, and they are somewhat simpler than java*compile.classpath, but they don't work on all JREs.

- The description of java15compile.classpath and java14compile.classpath says "The Derby tries to find". Should this be "The Derby build tries to find"?

[Rick Hillegas]

Thanks for the quick feedback, Knut. Attaching derby-3985-01-ab-simplerBuildInstructions.diff. This addresses most of your points:

1) Removes some unmatched closing tags. The html file still does not satisfy the W3C validator but I think that it is at least better-formed.

2) Adds a description of j14lib and j15lib

3) Fixes the wording of the description of java14compile.classpath and java15compile.classpath

I can't promise that the included images won't move, but they've stayed in the current location for a long time. If you browse to BUILDING.html while you're offline, the page should still come up; it just won't find the images.

[Myrna van Lunteren]

I haven't applied the patch & read the doc yet, but I wanted to mention:
1. I believe building.txt is referenced on the main derby site; at least on: http://db.apache.org/derby/dev/derby_source.html#How+to+build+Derby
Probably also mentioned on the wiki too.
These references need to get changed.
2. building.txt is part of the src. distribution during a release build. We need to make sure building.htm goes in its place.

[Rick Hillegas]

Thanks for pointing out those issues, Myrna. Attaching derby-3985-01-ac-simplerBuildInstructions.diff. This changes the release build to include BUILDING.html rather than BUILDING.txt. This changes another reference to BUILDING.txt in the testing README.htm. I will have to update the website after this change commits.

[Rick Hillegas]

Committed derby-3985-01-ac-simplerBuildInstructions.diff at subversion revision 731605.

[Rick Hillegas]

Attaching derby-3985-02-aa-website.diff. This cleans up the build instructions on the website and points the user to BUILDING.html rather than BUILDING.txt. Committed at subversion revision 731614.

[Rick Hillegas]

Updated the following wiki pages to reflect the simplified build and the conversion of BUILDING.txt to BUILDING.html:

http://wiki.apache.org/db-derby/BuildingDerby
http://wiki.apache.org/db-derby/DerbySnapshotOrRelease

[Rick Hillegas]

Attaching derby-3985-03-aa-corrections.diff. This corrects a typo in BUILDING.txt and adds some examples of settings for the classpath variables.

[Rick Hillegas]

Committed derby-3985-03-aa-corrections.diff at subversion revision 731650:

M BUILDING.html

[John H. Embretsen]

When I click the links to BUILDING.html on the web site or the wiki, I get the HTML source as plain text, which is not that easy to read, instead of a rendered HTML page. Not sure if it is browser-dependent; I have tried with Firefox and Opera. I don't know if this is something that could be fixed in SVN. As a workaround, using a different access method (viewvc) seems to do the trick:

This displays rendered HTML: http://svn.apache.org/viewvc/db/derby/code/trunk/BUILDING.html?view=co
This displays HTML source: http://svn.apache.org/repos/asf/db/derby/code/trunk/BUILDING.html

I also would like to note that although the document states that you need JUnit 3.8.1 to run the tests, I think JUnit 3.8.2 works equally well or better (unless I'm overlooking something).

Althugh I did not test or read the document's fine details, it looks good, tight and easy to follow. Well done!

[Rick Hillegas]

Hi John,

Thanks for the tip about how to pull subversion-controlled html files through viewvc. That trick works for me too using Firefox on Mac OS X. While I was in there, I also fixed the URL to the testing README page.

By the way, do you have a pointer to documentation for Viewvc? The website is a little terse: http://viewvc.tigris.org/

Attaching derby-3985-04-aa-fixViewvcURLs.diff, a patch which changes the URLs as you suggest. Touches the following files, committed at subversion revision 731942:

M build/site/dev/derby_source.html
M src/documentation/content/xdocs/dev/derby_source.xml

[Rick Hillegas]

Thanks for correcting the junit version also, John. It turns out I am also using 3.8.2. I've updated the junit version recommended by BUILDING.html. Attaching derby-3985-05-aa-junitVersion.diff, committed at subversion revision 731958.

[John H. Embretsen]

Thanks for updating the HTML links and JUnit version, Rick. Unfortunately I don't know about any documentation for Viewvc other than what's in their source trunk, e.g. http://viewvc.tigris.org/source/browse/*checkout*/viewvc/trunk/INSTALL