On 13 January 2015 at 12:44, Gilles <gil...@harfang.homelinux.org> wrote: > On Thu, 8 Jan 2015 15:49:31 +0000, sebb wrote: >> >> On 8 January 2015 at 11:59, Gilles <gil...@harfang.homelinux.org> wrote: >>> >>> On Thu, 8 Jan 2015 01:20:20 +0000, sebb wrote: >>>> >>>> >>>> On 8 January 2015 at 00:25, Gilles <gil...@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.neidh...@gmail.com> wrote: >>>>>>> >>>>>>> >>>>>>> >>>>>>> On 01/07/2015 06:00 PM, sebb wrote: >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> On 7 January 2015 at 16:29, Thomas Neidhart >>>>>>>> <thomas.neidh...@gmail.com> >>>>>>>> wrote: >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> On 01/07/2015 04:50 PM, sebb wrote: >>>>>>>>>> >>>>>>>>>> >>>>>>>>>> >>>>>>>>>> On 7 January 2015 at 13:59, Gilles <gil...@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. > 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) 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: 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-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
