On 1/13/15 10:48 AM, sebb wrote: > 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.
-1 to release examples jar > >> 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) Math has a working Ant build. > 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: Or use an Ant get-deps task like the math build itself does. Ant is a way better tool for this kind of thing than maven, IMO. Phil > > 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 > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
