commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <>
Subject Re: [Math] Maven profile for running the examples?
Date Thu, 08 Jan 2015 01:20:20 GMT
On 8 January 2015 at 00:25, Gilles <> wrote:
> On Wed, 7 Jan 2015 17:21:33 +0000, sebb wrote:
>> On 7 January 2015 at 17:12, Thomas Neidhart
>> <> wrote:
>>> On 01/07/2015 06:00 PM, sebb wrote:
>>>> On 7 January 2015 at 16:29, Thomas Neidhart <>
>>>> wrote:
>>>>> On 01/07/2015 04:50 PM, sebb wrote:
>>>>>> On 7 January 2015 at 13:59, Gilles <>
>>>>>> wrote:
>>>>>>>>> [...]
>>>>>>>> I have pushed the change to the userguide. To execute the
>>>>>>>> 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
>>>>>>>>  * 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
>>>>>> 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
>>>>>> 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
>>>>>> 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

> 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.


>> 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.

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.

If such examples did not need external dependencies, then the NET
approach would work.

> Gilles
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message