General outline for read.me.first

[Bruce Skelly]

Hi,

I would suggest the following for the general outline for the "read.me.first" file.

Purpose:  The purpose of the "read.me.first" file is to verify the minimum required software environment is available to compile netrexx programs.  Full installation instructions as well as problem resolution advise is contained in the file "NetRexx Quickstart Guide 3.01.pdf" located in the documents directory.

1. Verify the presence of java on the system executing the following command

java -version

A failure at this point indicates that either your PATH environmental variable doesn't include a path to java or java doesn't exist on your system. 

2. Set up an environmental variable to save a little typing, execute this command from the same directory that contains the "read.me.first" file.

export NRH=`pwd`

3. define a classpath

export CLASSPATH=$NRH/lib/NetRexxC.jar:$NRH/lib/ecj-4.2.jar:.

4. change directory to the directory containing hello.nrx

cd $NRH/examples/ibm-historic

5. compile hello.nrx

java -Dnrx.compiler=ecj org.netrexx.process.NetRexxC hello

java hello

Of course additional information for Windows systems would need to be included, as well as for csh users on UNIX/Linux/BSD systems.

So what do you think of this general outline?

Bruce 

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[rvjansen]

Bruce,

I like this, but I hope one day it can be shorter.

Our grief is caused by executing the compiler through the java class that implements it, and avoiding the compiler executable. This makes for a setup in which it is possible to have a path that allows for executing javac, which misses the classpath to execute the compiler - we can say that javac cheats because it knows the layout of its libraries on the filesystem. Tools.jar is not on the classpath, nor is it in the extensions directory, and still javac works.

The JavaCompiler API would raise the threshold to 1.6, which is more than we want at this moment. We could conditionally include it.

Just the last half hour I spent reading through the source of JRuby and guess what, they just 'system javac' with the generated sources, and avoid the problem this way. We also can do that of course, as  a fallback.

The more straightforward solution would be to integrate ecj into the NetRexxC.jar. For comparison, the latter is now 365K without the ecj java compiler and would be around 2MB with the compiler included. For comparison, JRuby counts in at 12 MB. This seems a small price to pay, seen the difficulties this forum and my email inbox indicate; otoh, it will not solve the problem in finding Object.class that we have with the IBM JVM's.

I think we must follow Oracle and modern practice in using the -cp option on the command line, as the first option (I tend to do that in makefiles that are shared, so as not to depend on individuals' profiles.) There is no escaping the CLASSPATH setting for anything but the most trivial application. 

Measures we take must first address the bad out-of-box experience we currently have for people that receive the missing class exception the first time; they will encounter the classpath later on in their NetRexx careers, but at least the first impression will be better. The main class setting of the NetRexxC.jar already is org.netrexx.process.NetRexxC, since 3.00, so adding ecj to the jar will avoid a lot of first time problems.

best regards,

René.

On 19 feb. 2013, at 17:57, Bruce Skelly <[hidden email]> wrote:

Hi,

I would suggest the following for the general outline for the "read.me.first" file.

Purpose:  The purpose of the "read.me.first" file is to verify the minimum required software environment is available to compile netrexx programs.  Full installation instructions as well as problem resolution advise is contained in the file "NetRexx Quickstart Guide 3.01.pdf" located in the documents directory.

1. Verify the presence of java on the system executing the following command

java -version

A failure at this point indicates that either your PATH environmental variable doesn't include a path to java or java doesn't exist on your system. 

2. Set up an environmental variable to save a little typing, execute this command from the same directory that contains the "read.me.first" file.

export NRH=`pwd`

3. define a classpath

export CLASSPATH=$NRH/lib/NetRexxC.jar:$NRH/lib/ecj-4.2.jar:.

4. change directory to the directory containing hello.nrx

cd $NRH/examples/ibm-historic

5. compile hello.nrx

java -Dnrx.compiler=ecj org.netrexx.process.NetRexxC hello

java hello

Of course additional information for Windows systems would need to be included, as well as for csh users on UNIX/Linux/BSD systems.

So what do you think of this general outline?

Bruce 

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[rvjansen]

Ok, I have made a proof of concept for this (http://netrexx.org/files/NetRexxF.jar) NOTE: NOT an official version but a snapshot of trunk.

The instruction for this would be:

1) Verify the working of java on your system with the command:

java -version

If this does not work, obtain a version at java.com and install it.

2) Create a file named hello.nrx in the directory that contains NetRexxF.jar, with the line:

say 'hello, netrexx world!'

3) In this directory, verify the working of the interpreter with:

java -jar NetRexxF.jar -exec hello

4) Verify the creating of a .class file using the compiler with:

java -Dnrx.compiler=ecj -jar hello

This should create hello.class, to be executed with the command:

java -cp NetRexxF.jar:. hello

(on windows, the colon should be a semicolon)

This should be enough for read.me.first and does not mention or require the word classpath. All the rosetta examples can be compiled and studied this way.

The Quickstart Guide should offer explanations of the new classpath option of NetRexxC, the class that is called for compilation, the batch files and ways to use javac and the JDK.

What do we think?

best regards,

René.

On 19 feb. 2013, at 23:31, René Jansen <[hidden email]> wrote:

Bruce,

I like this, but I hope one day it can be shorter.

Our grief is caused by executing the compiler through the java class that implements it, and avoiding the compiler executable. This makes for a setup in which it is possible to have a path that allows for executing javac, which misses the classpath to execute the compiler - we can say that javac cheats because it knows the layout of its libraries on the filesystem. Tools.jar is not on the classpath, nor is it in the extensions directory, and still javac works.

The JavaCompiler API would raise the threshold to 1.6, which is more than we want at this moment. We could conditionally include it.

Just the last half hour I spent reading through the source of JRuby and guess what, they just 'system javac' with the generated sources, and avoid the problem this way. We also can do that of course, as  a fallback.

The more straightforward solution would be to integrate ecj into the NetRexxC.jar. For comparison, the latter is now 365K without the ecj java compiler and would be around 2MB with the compiler included. For comparison, JRuby counts in at 12 MB. This seems a small price to pay, seen the difficulties this forum and my email inbox indicate; otoh, it will not solve the problem in finding Object.class that we have with the IBM JVM's.

I think we must follow Oracle and modern practice in using the -cp option on the command line, as the first option (I tend to do that in makefiles that are shared, so as not to depend on individuals' profiles.) There is no escaping the CLASSPATH setting for anything but the most trivial application. 

Measures we take must first address the bad out-of-box experience we currently have for people that receive the missing class exception the first time; they will encounter the classpath later on in their NetRexx careers, but at least the first impression will be better. The main class setting of the NetRexxC.jar already is org.netrexx.process.NetRexxC, since 3.00, so adding ecj to the jar will avoid a lot of first time problems.

best regards,

René.

On 19 feb. 2013, at 17:57, Bruce Skelly <[hidden email]> wrote:

Hi,

I would suggest the following for the general outline for the "read.me.first" file.

Purpose:  The purpose of the "read.me.first" file is to verify the minimum required software environment is available to compile netrexx programs.  Full installation instructions as well as problem resolution advise is contained in the file "NetRexx Quickstart Guide 3.01.pdf" located in the documents directory.

1. Verify the presence of java on the system executing the following command

java -version

A failure at this point indicates that either your PATH environmental variable doesn't include a path to java or java doesn't exist on your system. 

2. Set up an environmental variable to save a little typing, execute this command from the same directory that contains the "read.me.first" file.

export NRH=`pwd`

3. define a classpath

export CLASSPATH=$NRH/lib/NetRexxC.jar:$NRH/lib/ecj-4.2.jar:.

4. change directory to the directory containing hello.nrx

cd $NRH/examples/ibm-historic

5. compile hello.nrx

java -Dnrx.compiler=ecj org.netrexx.process.NetRexxC hello

java hello

Of course additional information for Windows systems would need to be included, as well as for csh users on UNIX/Linux/BSD systems.

So what do you think of this general outline?

Bruce 

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Jeff Hennick]

BIG improvement step!  Yes.

On 2/21/2013 4:55 PM, René Jansen wrote:

Ok, I have made a proof of concept for this (http://netrexx.org/files/NetRexxF.jar) NOTE: NOT an official version but a snapshot of trunk.

The instruction for this would be:

1) Verify the working of java on your system with the command:

java -version

If this does not work, obtain a version at java.com and install it.

2) Create a file named hello.nrx in the directory that contains NetRexxF.jar, with the line:

say 'hello, netrexx world!'

3) In this directory, verify the working of the interpreter with:

java -jar NetRexxF.jar -exec hello

4) Verify the creating of a .class file using the compiler with:

java -Dnrx.compiler=ecj -jar hello

This should create hello.class, to be executed with the command:

java -cp NetRexxF.jar:. hello

(on windows, the colon should be a semicolon)

This should be enough for read.me.first and does not mention or require the word classpath. All the rosetta examples can be compiled and studied this way.

The Quickstart Guide should offer explanations of the new classpath option of NetRexxC, the class that is called for compilation, the batch files and ways to use javac and the JDK.

What do we think?

best regards,

René.

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Kermit Kiser]

I suspect that you meant this line:

java -Dnrx.compiler=ecj -jar hello

to be like this:

java -Dnrx.compiler=ecj -jar NetRexxF.jar hello

In the general case, I would recommend against using "-jar" because that option causes ALL classpath information to be silently ignored.

Does item #2 indicate that the hello.nrx originally included with NetRexx distributions is now gone?

-- Kermit

On 2/21/2013 11:55 AM, René Jansen wrote:

Ok, I have made a proof of concept for this (http://netrexx.org/files/NetRexxF.jar) NOTE: NOT an official version but a snapshot of trunk.

The instruction for this would be:

1) Verify the working of java on your system with the command:

java -version

If this does not work, obtain a version at java.com and install it.

2) Create a file named hello.nrx in the directory that contains NetRexxF.jar, with the line:

say 'hello, netrexx world!'

3) In this directory, verify the working of the interpreter with:

java -jar NetRexxF.jar -exec hello

4) Verify the creating of a .class file using the compiler with:

java -Dnrx.compiler=ecj -jar hello

This should create hello.class, to be executed with the command:

java -cp NetRexxF.jar:. hello

(on windows, the colon should be a semicolon)

This should be enough for read.me.first and does not mention or require the word classpath. All the rosetta examples can be compiled and studied this way.

The Quickstart Guide should offer explanations of the new classpath option of NetRexxC, the class that is called for compilation, the batch files and ways to use javac and the JDK.

What do we think?

best regards,

René.

On 19 feb. 2013, at 23:31, René Jansen <[hidden email]> wrote:

Bruce,

I like this, but I hope one day it can be shorter.

Our grief is caused by executing the compiler through the java class that implements it, and avoiding the compiler executable. This makes for a setup in which it is possible to have a path that allows for executing javac, which misses the classpath to execute the compiler - we can say that javac cheats because it knows the layout of its libraries on the filesystem. Tools.jar is not on the classpath, nor is it in the extensions directory, and still javac works.

The JavaCompiler API would raise the threshold to 1.6, which is more than we want at this moment. We could conditionally include it.

Just the last half hour I spent reading through the source of JRuby and guess what, they just 'system javac' with the generated sources, and avoid the problem this way. We also can do that of course, as  a fallback.

The more straightforward solution would be to integrate ecj into the NetRexxC.jar. For comparison, the latter is now 365K without the ecj java compiler and would be around 2MB with the compiler included. For comparison, JRuby counts in at 12 MB. This seems a small price to pay, seen the difficulties this forum and my email inbox indicate; otoh, it will not solve the problem in finding Object.class that we have with the IBM JVM's.

I think we must follow Oracle and modern practice in using the -cp option on the command line, as the first option (I tend to do that in makefiles that are shared, so as not to depend on individuals' profiles.) There is no escaping the CLASSPATH setting for anything but the most trivial application. 

Measures we take must first address the bad out-of-box experience we currently have for people that receive the missing class exception the first time; they will encounter the classpath later on in their NetRexx careers, but at least the first impression will be better. The main class setting of the NetRexxC.jar already is org.netrexx.process.NetRexxC, since 3.00, so adding ecj to the jar will avoid a lot of first time problems.

best regards,

René.

On 19 feb. 2013, at 17:57, Bruce Skelly <[hidden email]> wrote:

Hi,

I would suggest the following for the general outline for the "read.me.first" file.

Purpose:  The purpose of the "read.me.first" file is to verify the minimum required software environment is available to compile netrexx programs.  Full installation instructions as well as problem resolution advise is contained in the file "NetRexx Quickstart Guide 3.01.pdf" located in the documents directory.

1. Verify the presence of java on the system executing the following command

java -version

A failure at this point indicates that either your PATH environmental variable doesn't include a path to java or java doesn't exist on your system. 

2. Set up an environmental variable to save a little typing, execute this command from the same directory that contains the "read.me.first" file.

export NRH=`pwd`

3. define a classpath

export CLASSPATH=$NRH/lib/NetRexxC.jar:$NRH/lib/ecj-4.2.jar:.

4. change directory to the directory containing hello.nrx

cd $NRH/examples/ibm-historic

5. compile hello.nrx

java -Dnrx.compiler=ecj org.netrexx.process.NetRexxC hello

java hello

Of course additional information for Windows systems would need to be included, as well as for csh users on UNIX/Linux/BSD systems.

So what do you think of this general outline?

Bruce 

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[rvjansen]

Kermit,

yes, that is what I meant.

Using -jar this way has the undeniable advantage of having the out-of-the-box experience always work.

The new -classpath option on NetRexx enables compiling with libraries in real applications:

java -Dnrx.compiler=ecj -jar NetRexxF.jar -classpath NetRexxF.jar:/Users/rvjansen/lib/org.eclipse.paho.client.mqttv3.jar:. YourProgram.nrx

Note that in this case, we need the NetRexxF jar repeated on the NetRexxC classpath. Also, in this case, the shorter version would be to default to ecj compiles.

And, we are taking nothing away from the experienced user: we are only making it possible to avoid the classpath environment variable or dumping everything in the extensions library.

I was planning to point to the hello.nrx that is already included in the historic IBM example directory; it might be more satisfying to the first time user to type it in.

best regards,

René.

 

On 21 feb. 2013, at 23:56, Kermit Kiser <[hidden email]> wrote:

I suspect that you meant this line:

java -Dnrx.compiler=ecj -jar hello

to be like this:

java -Dnrx.compiler=ecj -jar NetRexxF.jar hello

In the general case, I would recommend against using "-jar" because that option causes ALL classpath information to be silently ignored.

Does item #2 indicate that the hello.nrx originally included with NetRexx distributions is now gone?

-- Kermit

On 2/21/2013 11:55 AM, René Jansen wrote:

Ok, I have made a proof of concept for this (http://netrexx.org/files/NetRexxF.jar) NOTE: NOT an official version but a snapshot of trunk.

The instruction for this would be:

1) Verify the working of java on your system with the command:

java -version

If this does not work, obtain a version at java.com and install it.

2) Create a file named hello.nrx in the directory that contains NetRexxF.jar, with the line:

say 'hello, netrexx world!'

3) In this directory, verify the working of the interpreter with:

java -jar NetRexxF.jar -exec hello

4) Verify the creating of a .class file using the compiler with:

java -Dnrx.compiler=ecj -jar hello

This should create hello.class, to be executed with the command:

java -cp NetRexxF.jar:. hello

(on windows, the colon should be a semicolon)

This should be enough for read.me.first and does not mention or require the word classpath. All the rosetta examples can be compiled and studied this way.

The Quickstart Guide should offer explanations of the new classpath option of NetRexxC, the class that is called for compilation, the batch files and ways to use javac and the JDK.

What do we think?

best regards,

René.

On 19 feb. 2013, at 23:31, René Jansen <[hidden email]> wrote:

Bruce,

I like this, but I hope one day it can be shorter.

Our grief is caused by executing the compiler through the java class that implements it, and avoiding the compiler executable. This makes for a setup in which it is possible to have a path that allows for executing javac, which misses the classpath to execute the compiler - we can say that javac cheats because it knows the layout of its libraries on the filesystem. Tools.jar is not on the classpath, nor is it in the extensions directory, and still javac works.

The JavaCompiler API would raise the threshold to 1.6, which is more than we want at this moment. We could conditionally include it.

Just the last half hour I spent reading through the source of JRuby and guess what, they just 'system javac' with the generated sources, and avoid the problem this way. We also can do that of course, as  a fallback.

The more straightforward solution would be to integrate ecj into the NetRexxC.jar. For comparison, the latter is now 365K without the ecj java compiler and would be around 2MB with the compiler included. For comparison, JRuby counts in at 12 MB. This seems a small price to pay, seen the difficulties this forum and my email inbox indicate; otoh, it will not solve the problem in finding Object.class that we have with the IBM JVM's.

I think we must follow Oracle and modern practice in using the -cp option on the command line, as the first option (I tend to do that in makefiles that are shared, so as not to depend on individuals' profiles.) There is no escaping the CLASSPATH setting for anything but the most trivial application. 

Measures we take must first address the bad out-of-box experience we currently have for people that receive the missing class exception the first time; they will encounter the classpath later on in their NetRexx careers, but at least the first impression will be better. The main class setting of the NetRexxC.jar already is org.netrexx.process.NetRexxC, since 3.00, so adding ecj to the jar will avoid a lot of first time problems.

best regards,

René.

On 19 feb. 2013, at 17:57, Bruce Skelly <[hidden email]> wrote:

Hi,

I would suggest the following for the general outline for the "read.me.first" file.

Purpose:  The purpose of the "read.me.first" file is to verify the minimum required software environment is available to compile netrexx programs.  Full installation instructions as well as problem resolution advise is contained in the file "NetRexx Quickstart Guide 3.01.pdf" located in the documents directory.

1. Verify the presence of java on the system executing the following command

java -version

A failure at this point indicates that either your PATH environmental variable doesn't include a path to java or java doesn't exist on your system. 

2. Set up an environmental variable to save a little typing, execute this command from the same directory that contains the "read.me.first" file.

export NRH=`pwd`

3. define a classpath

export CLASSPATH=$NRH/lib/NetRexxC.jar:$NRH/lib/ecj-4.2.jar:.

4. change directory to the directory containing hello.nrx

cd $NRH/examples/ibm-historic

5. compile hello.nrx

java -Dnrx.compiler=ecj org.netrexx.process.NetRexxC hello

java hello

Of course additional information for Windows systems would need to be included, as well as for csh users on UNIX/Linux/BSD systems.

So what do you think of this general outline?

Bruce 

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/