On Tue, 13 Jan 2015 11:03:42 -0700, Phil Steitz wrote:
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
It was not meant to be the current discussion (cf. earlier posts).
[It might become relevant when the examples are more than... examples.]
What about my other proposal, about setting up code that generates
reports (to be included in the "user guide" document)?
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.
I'd prefer the minimum number of ways to achieve the goal.
If we don't release the examples, ever, then the "maven -q exec:java"
way is fine (since the developers most likely have maven installed).
If we release something (e.g. part of the examples), it looks like
the simplest and safest way (license-wise) is to write down the list
of dependencies and let the users use "whatever" to collect the
dependencies and run the code...
Regards,
Gilles
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
