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