On a meta-issue, should we be editing the results and ideas into a file
in SVN, or plan to review these threads later?
I hope we can end up with full, well-tested instructions for a few
different environments.
On 2/8/2015 7:48 AM, Greg Trasuk wrote:
Thanks for trying this out… Some answers below…
Cheers,
Greg Trasuk
On Feb 8, 2015, at 4:33 AM, Patricia Shanahan <p...@acm.org> wrote:
Thanks very much for getting this done.
I am playing naive new user. I checked out the svn files, and viewed
README.md. Note that it might be nice to provide it as a README.txt as
well - a user who is getting the code from SVN may not be familiar with
Github conventions.
I was thinking that README.anything was likely to get the user’s first
attention, and that the md text was still readable as text. But I see your
point - it’s trivial to include a README.txt as well.
I think the instructions need a bit more information:
"To build the examples, simply unpack the source distribution of
'river-examples',
and then,
cd river-examples
mvn install
mvn site"
What am I supposed to unpack? How do I unpack it?
Instructions need clarification here - you pulled it from cvs, so it’s not “the
source distribution”,
which would have been in a “.tgz” file.
Actually SVN, not CVS, but same principle.
A readme file should assume the user reads it at the first point at
which the readme becomes accessible, no earlier. Is the readme going to
be inside the .tgz, or outside it? What is a .tgz?
It should say where to type this. Windows command tool? Cygwin shell?
Unix/Linux shell? I assume I need a JDK, but that should be specified.
Which JDK versions?
I skipped the "unpack" part of the instructions and used Netbeans. I
created a new Maven project from existing POM, and built it. I then used
right click on project, Custom, Goals to run "install" and "site". That
all worked fine, including smoothly downloading from Maven Central.
I opened the index.html file that resulted. Clicking on e.g. the
"browser" link got "Firefox can't find the file at
/C:/river-examples/target/site/browser/index.html.". The browser
directory contains a file "browser-start.png" but no "index.html”.
Ahh… Need for more instructions here. Netbeans bundles an older version of
Maven that doesn’t understand Markdown text in the site generation. What you
need to do is install the latest Maven from ‘maven.apache.org’ and configure
Netbeans to use it. I’ll add a note to the instructions (although this is
really Maven setup). For your immediate use,
- Download Maven 3.2.5 from http://maven.apache.org/download.cgi. If you’re on
Windows, download the zip file. If on Linux/Unix, get the “.tar.gz”.
- Unpack it to a convenient directory (Windows: right-click on the zip and
select “Extract all”. OSX: Just open the tar.gz file. *nix: should be
something like ‘tar xvzf apache-maven-3.2.5.bin.tar.gz
/usr/local/apache-maven-3.2.5
- In Netbeans, select Preferences (OSX: Netbeans —> Preferences. Windows: Tools
—> Options) then select the “Maven” tab) and then set the Maven Home field to
point to your local installation.
For Windows, it is Tools -> Option ->Java -> Maven
Then, I suspect you’ll need to do a Custom —> clean install site.
Did that, followed by the "install" and "site" goals. There were several
warnings. Would you like the console output, or are they expected?
I suppose the smart thing to do is just publish the examples documentation
to the River Web site when we release it -that would replace the
“Getting started” page.
Yes, I see the end point of this exercise as a much better "Getting
started" page.
Thanks again for your efforts.
Patricia
On 2/7/2015 6:27 AM, Greg Trasuk wrote:
Hi all:
This doesn’t seem to have gone through the mail system yesterday, so
I’m posting again. Apologies if we eventually have a storm of
similar messages.
Hi all:
Finally finished the examples project. Please review and comment.
You can get it from svn at
https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk
My thinking is that a new user trying out the examples will start
with the read me file at: “README.md” (formatted as markdown so that
in case someone is looking at the github mirror, they’ll see it on
the front page of the project). So, if one or more of you could
checkout the project and begin by following the README.md
instructions, that would give us a feel for the “new-user”
experience.
I’m picturing that we should be able to release the examples project
fairly quickly, and then start trying to publicize it. Also, we can
add more advanced examples as time goes on (e.g. event notifications,
transactions, JavaSpaces, web app client, etc).
Thanks,
Greg Trasuk.
