commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
Subject Re: [Math] Maven profile for running the examples?
Date Tue, 13 Jan 2015 18:03:42 GMT
On 1/13/15 10:48 AM, sebb wrote:
> On 13 January 2015 at 12:44, Gilles <gilles@harfang.homelinux.org> wrote:
>> On Thu, 8 Jan 2015 15:49:31 +0000, sebb wrote:
>>> On 8 January 2015 at 11:59, Gilles <gilles@harfang.homelinux.org> wrote:
>>>> On Thu, 8 Jan 2015 01:20:20 +0000, sebb wrote:
>>>>>
>>>>> On 8 January 2015 at 00:25, Gilles <gilles@harfang.homelinux.org>
wrote:
>>>>>>
>>>>>> On Wed, 7 Jan 2015 17:21:33 +0000, sebb wrote:
>>>>>>>
>>>>>>>
>>>>>>> On 7 January 2015 at 17:12, Thomas Neidhart
>>>>>>> <thomas.neidhart@gmail.com> wrote:
>>>>>>>>
>>>>>>>>
>>>>>>>> On 01/07/2015 06:00 PM, sebb wrote:
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On 7 January 2015 at 16:29, Thomas Neidhart
>>>>>>>>> <thomas.neidhart@gmail.com>
>>>>>>>>> wrote:
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> On 01/07/2015 04:50 PM, sebb wrote:
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> On 7 January 2015 at 13:59, Gilles <gilles@harfang.homelinux.org>
>>>>>>>>>>> wrote:
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> [...]
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>> I have pushed the change to the userguide.
To execute the
>>>>>>>>>>>>> example
>>>>>>>>>>>>> you do
>>>>>>>>>>>>> the following:
>>>>>>>>>>>>>
>>>>>>>>>>>>>  * go to commons-math folder, type mvn
clean install
>>>>>>>>>>>>>    this step is only needed if your local
maven repository does
>>>>>>>>>>>>> not
>>>>>>>>>>>>> yet
>>>>>>>>>>>>>    contain the latest commons-math snapshot
>>>>>>>>>>>>>  * go to userguide folder (src/userguide),
type mvn clean
>>>>>>>>>>>>> package
>>>>>>>>>>>>>  * now you can run the examples like
that:
>>>>>>>>>>>>>
>>>>>>>>>>>>> java -cp target/commons-math3-examples-uber-3.5-SNAPSHOT.jar
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>> org.apache.commons.math3.userguide.LowDiscrepancyGeneratorComparison
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>> Very nice.
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> Yes, however there is a caveat.
>>>>>>>>>>> The uber jar must not be published, at least
in its current form.
>>>>>>>>>>> - it contains un-shaded classes that have different
Maven coords
>>>>>>>>>>> (=>
>>>>>>>>>>> jar hell)
>>>>>>>>>>> - it does not have N&L files
>>>>>>>>>>> - are the 3rd party jars AL compatible?
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> there is no intention to publish the uber jar.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> OK.
>>>>>>>>>
>>>>>>>>>>> There is another way to run the code without
needing to generate
>>>>>>>>>>> the
>>>>>>>>>>> jars:
>>>>>>>>>>>
>>>>>>>>>>> cd src/userguide
>>>>>>>>>>>
>>>>>>>>>>> mvn -q exec:java
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> -Dexec.mainClass=org.apache.commons.math3.userguide.LowDiscrepancyGeneratorComparison
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> nice, did not know this trick before.
>>>>>>>>>>
>>>>>>>>>>> This uses Maven to resolve the dependencies.
>>>>>>>>>>>
>>>>>>>>>>> Works very well for developer testing of examples.
>>>>>>>>>>> However it is not so useful for end users as
they would need Maven
>>>>>>>>>>> and
>>>>>>>>>>> the Math source.
>>>>>>>>>>>
>>>>>>>>>>> The NET jar method works well because there are
no external
>>>>>>>>>>> dependencies, and the example jar is created
in the same directory
>>>>>>>>>>> as
>>>>>>>>>>> the core jar it depends on.
>>>>>>>>>>>
>>>>>>>>>>> The same approach would work for Math, but the
user would have to
>>>>>>>>>>> download the additional dependencies somehow.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> the approach with exec:java is good enough imho,
as >90% of the
>>>>>>>>>> users
>>>>>>>>>> will have maven installed.
>>>>>>
>>>>>>
>>>>>>
>>>>>> Agreed.
>>>>>> It's safe to assume that (see below for the proposed usage).
>>>>>>
>>>>>>>>> But they won't necessarily have the Math source.
>>>>>>>>>
>>>>>>>>> On a whim I just tried creating a basic pom with only
the
>>>>>>>>> dependencies.
>>>>>>>>> I added examples as another dependency.
>>>>>>>>>
>>>>>>>>> This works fine with exec:java from any directory provided
only that
>>>>>>>>> the examples have been installed (or can be found from
a repo)
>>>>>>>>>
>>>>>>>>> A minor disadvantage of exec:java is one has to use properties
for
>>>>>>>>> the
>>>>>>>>> main class and arguments - the syntax is a bit awkward.
>>>>>>
>>>>>>
>>>>>>
>>>>>> I did not follow the details (e.g. what is "uber"?) but IMHO, one
>>>>>> simple
>>>>>
>>>>>
>>>>> The uber jar is a jar that contains the examples classes and all its
>>>>> dependencies.
>>>>>
>>>>>> enough way is enough; the simpler the "pom.xml" the better (perhaps
>>>>>> with
>>>>>> a little README in the same directory).
>>>>>
>>>>>
>>>>> The src/userguide/pom.xml compiles the examples and creates the uber
>>>>> jar.
>>>>> The section that creates the uber jar could be dropped and it would
>>>>> still be suitable for use with exec:java
>>>>>
>>>>>>>> the examples are also not published (yet), thus there is
no way to
>>>>>>>> run
>>>>>>>> the examples without downloading the source distribution
(or checkout
>>>>>>>> the git repo).
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Yes, but the code we are discussing is for the next release.
>>>>>>
>>>>>>
>>>>>>
>>>>>> Not necessarily.
>>>>>> The first step was necessarily to be able to compile and run them
>>>>>> for ourselves.
>>>>>
>>>>>
>>>>> OK
>>>>>
>>>>>>> I think it would make sense to include the compiled examples
in the
>>>>>>> release as a separate jar.
>>>>>>
>>>>>>
>>>>>>
>>>>>> IMO, the setup in the "src/userguide" can have at least two purposes
>>>>>> that are more useful than publishing the compiled examples:
>>>>>>  1. Generate reports (on various aspects of CM) to be integrated
in
>>>>>>     "userguide" document. [For this, the build must run the code
>>>>>>     that generates the reports.]
>>>>>>  2. Publish source code of working examples. [For this, the RM
>>>>>>     must of course ensure that the code is correct (i.e. compiles
>>>>>>     and runs as expected).]
>>>>>>
>>>>>> Providing compiled code is only useful if the examples are more
>>>>>> than just toy problems, and provide readily useful functionalities:
>>>>>> a library of real-world applications (in which the name "examples"
>>>>>> won't be appropriate anymore).  [We are not there yet (the idea of
>>>>>> real-world examples was proposed quite some time ago but did not
>>>>>> elicit any comment IIRC).]
>>>>>
>>>>>
>>>>> By contrast the NET examples are all (or mostly) usable.
>>>>>
>>>>>> Points (1) and (2) would add to the resources which a newcomer
>>>>>> might like to read to get acquainted with the contents of the
>>>>>> library. The document should be readily available without a
>>>>>> prospective user having to run anything.
>>>>>>
>>>>> Well of course.
>>>>
>>>>
>>>> So we need to set up a list of desirable reports...
>>>> [One that comes to mind is a benchmark of FastMath.]
>>>>
>>>>> If the examples were extended to include useful utilities, then I
>>>>> suspect you would find some people wanted to be able to run them
>>>>> without needing to install Maven and a JDK.
>>>>> In which case one way to do this is via a uber jar.
>>>>> That would only require a Java runtime.
>>>>
>>>>
>>>> I understand, but since there are no such utilities, better avoid
>>>> potential license problems. I.e. let's first decide which examples
>>>> are broadly, then publish only those when the time comes, and this
>>>> in turn will require more fine-grained control of the build.
>>>> So IMHO, it's better to remove the "uber" setup (if just so that
>>>> we limit the things that might break, or that the thing that might
>>>> break will be discovered sooner since we'd all use the same tool).
>>>>
>>>>> If such examples did not need external dependencies, then the NET
>>>>> approach would work.
>>>>
>>>>
>>>> And, as suggested above, perhaps that the published compiled
>>>> examples won't have the problematic dependencies...
>>>
>>> There's another way round the uber jar. Requires Maven and Java
>>> runtime but not JDK.
>>>
>>> That is to provide the dependency POM I mentioned earlier.
>>>
>>> It will download the dependencies to the local Maven repo if necessary.
>>>
>>> I'll add a sample to JIRA so people can try it.
>>>
> https://issues.apache.org/jira/browse/MATH-1187
>
>> Do I understand correctly that, for the developers, it will amount to
>> modularizing the "pom.xml" without changing the behaviour (of maven),
>> and using the same "exec" incantation?
> It uses a separate minimal POM, see the JIRA.
> The suggested POM is optional, and assumes the examples jar has been
> released to Maven.

-1 to release examples jar
>
>> Users of CM that don't use maven, would be forced to install it, if
>> they want to run the examples.
> No, there is no need to install Maven if CM releases the examples as a jar.
> [However obviously the MATH-1187 POM would be no use to them.]
>
> But if CM does not release the examples jar then a CM user that does
> not want to install Maven may have a problem.
>
> The standard way to build CM Math from source is to use Maven.
> So unless CM provides a separate build method (Ant, or setup files for
> different IDEs, or shell scripts for different OSes)

Math has a working Ant build.

>  the user is going
> to have to work out how to build the examples for themselves.
> [CM can provide written build instructions, but the user would have to
> translate those into their own build tools]
>
> And (to state the obvious) if a CM user only has runtime Java and does
> not want to install a JDK, then their only hope is if CM Math releases
> the examples as a compiled jar.
>
> In the case of a CM user without Maven, the user needs to be told what
> dependencies are needed by the examples.
> They then need to download all the dependencies and ensure that they
> are available on the classpath when running the examples.
>
> One way to do this is to ensure that the jars are all in the same directory.
> The examples jar manifest can include a Classpath entry which can list
> the jars; there is then no need to list them on the java command line
> (and possibly not in the pom dependency section either)
> And if the manifest has a Main-Class entry, it can be invoked as follows:

Or use an Ant get-deps task like the math build itself does.  Ant is
a way better tool for this kind of thing than maven, IMO.

Phil
>
> java -jar examples.jar
>
> If you want to experiment, I suggest you try downloading the commons-net jars.
>
>> [Anyways, we can leave the discussion about what and how to release
>> the examples when the time comes...]
> There are various options to try out so I would advise not leaving it
> until the last minute.
>
>>
>> Gilles
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message