commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles <gil...@harfang.homelinux.org>
Subject Re: [Math] Maven profile for running the examples?
Date Thu, 08 Jan 2015 11:59:34 GMT
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...


Gilles



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


Mime
View raw message