Mailing-List: contact dev-help@river.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@river.apache.org
Received-SPF: error (nike.apache.org: local policy)
Content-Type: text/plain; charset=windows-1252
Mime-Version: 1.0 (Mac OS X Mail 7.3 \(1878.6\))
Subject: Re: Getting Started
From: Greg Trasuk <trasukg@stratuscom.com>
In-Reply-To: <54AECE7B.3050105@acm.org>
Date: Thu, 8 Jan 2015 15:55:01 -0500
Content-Transfer-Encoding: quoted-printable
Message-Id: <86B5D164-1410-42BE-949B-3155BE497F05@stratuscom.com>
References: <54AB191F.6060305@acm.org>
 <E648A25F-56B9-4502-9F11-C0E4613572DC@stratuscom.com>
 <54AECE7B.3050105@acm.org>
To: dev@river.apache.org


Hi Patricia:

Maven is pretty mainstream at this point in time (very much in open =
source, it=92s also beginning to hit the later adopters in the corporate =
world).

Having said that, the Maven site makes it look much harder than it is.  =
Let me boil it down a little.

1 - =46rom the command line...
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D

- Download the latest Maven from http://maven.apache.org/download.cgi
  - You probably want the binary zip
- Unpack that file somewhere convenient
- The unpacked file contains a =91bin=92 folder.  Put that =91bin=92 =
folder in your command path
- At the command line, type =91mvn -version=92. Does that run?  If yes, =
you=92ve installed Maven.
- Now you can go to the project directory, e.g. river-examples, and type =
=91mvn install=92.

2 - =46rom Netbeans
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

- Netbeans includes Maven 3.0.5, which I don=92t think has the markdown =
processor for the documents that I created.  So it=92s better to use a =
local Maven installation, so=85
- Download the latest Maven from http://maven.apache.org/download.cgi
  - You probably want the binary zip
- Unpack that file somewhere convenient.  This is your =93Maven =
Installation=94 dir.
- In Netbeans, select Preferences - > Java -> Maven and point it to the =
unpacked Maven dir.

3 - What Maven Does=85
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

Maven processes a set of source files and/or submodules to produce an =
=91artifact=92.  Typically an artifact is a jar file, but it could also =
be an unpacked directory.

We talk about a =91Maven Module=92.  This is a folder that contains a =
file called =91pom.xml=92 and all the source code and/or submodules.  =
Source code is under =91src=92.  Anything produced by Maven is under =
=91target=92.  =91pom.xml=92 is essentially a description of the =
artifact.  In particular, it includes a list of artifacts that this =
artifact depends on.  One module should produce one artifact.  When we =
have more than one artifact, or an artifact that depends on other =
artifacts, we use a =93Multi-module=94 project.  This is simply a module =
who=92s =91pom.xml=92 specifies submodules.

Maven processes your source file, based on the requirements in =91pom.xml=92=
 to produce an artifact.  Typically this artifact gets installed in a =
local repository, that usually resides in ~/.m2/repository.  Typing =91mvn=
 install=92 in the module folder tells Maven to do this installation.  =
Maven is bright enough to know that it has to compile and package the =
artifact first.

While doing the build, if Maven finds a dependency that it doesn=92t =
already have a copy of, it goes off to a central repository called =
=91Maven Central=92 and downloads it to your local repository.  All of =
River=92s compiled jars are available through Maven Central.

Hopefully that makes my previous explanation make a little more sense.  =
If not, just shout=85

Cheers,

Greg Trasuk.


On Jan 8, 2015, at 1:37 PM, Patricia Shanahan <pats@acm.org> wrote:

> For me, the next step in this flow is to learn Maven.
>=20
> In general, is it reasonable to assume that, if I had been working =
actively as a programmer for the last few years, I would have already =
learned Maven?
>=20
> If not, we need to document, at least by reference, the steps involved =
to get far enough along with Maven to try out River.
>=20
> Patricia
>=20
> On 1/5/2015 7:16 PM, Greg Trasuk wrote:
>>=20
>> I started working on making new demos and =93getting started=94 stuff
>> back before the holidays.  Here=92s my thinking=85
>>=20
>> As Patricia alludes to, it really shouldn=92t be necessary to build =
the
>> River distribution in order to try out some samples and get started.
>> After all, the artifacts are published on Maven Central, so they can
>> simply be referenced in a Maven build (or Gradle, Ivy, Etc).
>>=20
>> Towards that end, I started building a new Mavenized =91examples=92
>> project, which can be checked-out from
>> =
https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk=
.
>>=20
>> In that project, there are currently modules for the service browser
>> jars and a =91home=92 folder for the compiled and packaged examples.
>> (might be best to download it and do a =91mvn install site=92).  =
There=92s
>> also documentation for the examples under the main project (look at
>> <project-home>/target/site/index.html - this should be familiar to
>> Maven users).  The documentation currently includes how to build and
>> run the service browser (although I think right now it=92s incomplete
>> on how the configuration works - haven=92t looked at it since Dec =
15).
>>=20
>> Right now, the project has a dependency on the new =91river-rt-tools=92=

>> modules that I talked about back in December as well.  So in order to
>> run the examples, you currently need to checkout
>> 'https://svn.apache.org/repos/asf/river/river-rt-tools/trunk' and do
>> a =91mvn install=92 on it, which will install the runtime tool =
artifacts
>> (start.jar) in your local Maven cache.  In the end, those artifacts
>> would also be released and published on Maven Central, so you
>> eventually wouldn=92t need to build the runtime tools separately.
>>=20
>> My plan is to add modules to the river-examples project for a
>> 'hello-service=92 and =91hello-client=92, as well as a config for the
>> infrastructure services (Reggie, etc).  So eventually, the =93getting
>> started=94 instructions become =93have a look at =91river-examples=92=94=
, and
>> we=92d remove the (very confusing, if you ask me) =91examples=92 =
folder
>> from the JTSK distribution.  As a bonus, we can isolate new users
>> from the convoluted build system in River.
>>=20
>> If this seems like a reasonable path forward for our =93getting
>> started=94 experience, perhaps you=92d like to work on bringing over =
some
>> of the examples from the JTSK to the =91river-examples=92 project. =
That=92s
>> probably also a good way to re-familiarize yourself with Jini.  I
>> probably won=92t have any cycles to work on it seriously for the next
>> couple weeks, but could cheerfully make suggestions.
>>=20
>> You should be able to check-out these two Maven project in the IDE of
>> your choice.  I was using NetBeans, but AFAIK, Eclipse should be able
>> to use the Maven build directly.  I just haven=92t tried it.
>>=20
>> Cheers,
>>=20
>> Greg Trasuk.
>>=20
>> On Jan 5, 2015, at 6:07 PM, Patricia Shanahan <pats@acm.org> wrote:
>>=20
>>> I have completed buying a new home, moving into it, and selling the
>>> old one, followed by Christmas in England and recovery from the
>>> cold I caught there. That means I'm ready to get much more active
>>> in River.
>>>=20
>>> Last year, we got some feedback suggesting that better support for
>>> new users might remove a barrier to community building. My main
>>> agenda is community building, so I want to work on that. I am going
>>> to be a very naive potential user, so stand by for basic
>>> questions.
>>>=20
>>> I began by downloading the binary version, since in this mode I am
>>> not interested in being a River developer. However, when I looked
>>> at the "Getting Started" page,
>>> river.apache.org/user-guide-basic-river-services.html, it says:
>>>=20
>>> "The instructions assume that you're building from source as
>>> checked out from the SVN trunk. Currently this is necessary because
>>> the code snippets below use methods and classes which, at time of
>>> writing, haven't made it into the latest binary release yet. Having
>>> said that, the code you will need in the binary release isn't to
>>> far removed from what you'll see below, so you can progress with
>>> the binary release if you want to and are happy odifying the
>>> code."
>>>=20
>>> According to the page info, the "time of writing" was no later than
>>> November 23, 2013. Do I still need to do a River build before I can
>>> run the example? If so, why and what can I do to fix that?
>>>=20
>>> I have no idea whether or not I would be happy "odifying" code -
>>> maybe "modifying"?
>>>=20
>>> What is the best procedure for editing the "Getting Started" page?
>>> I want to make sure that any changes I make really are
>>> improvements, so I would like PMC review as I go along.
>>>=20
>>> Patricia
>>>=20
>>>=20
>>=20