commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
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 <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.

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