Draft JEP: Launch Single-File Source-Code Programs

[Jonathan Gibbons]

On 02/08/2018 03:18 PM, Jonathan Gibbons wrote:
> This draft JEP contains a proposal to enhance the |java| launcher to 
> support running a
> program supplied as a single file of Java source code. The program 
> will be compiled
> and run, without the need to explicit invoke javac, or to package up a 
> jar file.
>
> For more details, see:
>
> http://openjdk.java.net/jeps/8192920
>
> -- Jon

Following up on this ...

Thanks to all for the discussion.  A number of interesting points were 
raised:

1. A desire to be able to specify the source version of the code to be 
compiled
2. A desire to specify additional VM options, most notably options like 
-Xmx or a classpath
3. General concerns with the limitations of the OS-provided shebang 
mechanism,
     especially related to how arguments are passed from the OS to the 
executable.

To address these concerns, I propose to make the following two changes 
to the JEP.
The first is user-visible, the second is mostly under-the-covers 
implementation detail.

1. Change the "-- source" option from being a simple no-arg option to an 
option that
takes a release number, in line with the values currently accepted by 
the javac
-source and --release options.  In line with JEP 293, Guidelines for JDK 
Command-Line
Tool Options, the value can be separated from the option name either by 
white space
or an '='.

2. Change the Java Launcher so that if the first option begins with 
`--source`
and contains white space, it will be split in-place into words separated 
by white space.
This behavior will be limited as described so as not to affect the use 
of any other
other options that may contain whitespace. The behavior is justified because
the OS shebang mechanism is the underlying cause of the issue and the 
--source
option is primarily intended for use in shebang files, to identify the 
use of a source
file that does not follow the normal source-file naming conventions. The 
spec
is intended to cover both cases, where the OS shebang mechanism passes 
the rest of
the first line as a single arg to the executable, and where the OS 
itself breaks the rest
of the line into words separated by whitespace.

---

With these two modifications to the JEP proposal in mind, here are a 
bunch of examples
to illustrate both simple and more advanced use cases. The shebang 
examples are
obviously limited to those OS environments that provide a shebang 
feature, meaning
primarily Unix-derived systems, like Linux, MacOS and Solaris.

1.  A simple program in a source file named in the standard fashion

     $ java HelloWorld.java

2. A program that needs additional VM options

     $ java -Xmx1024m -Dplanet=Jupiter HelloPlanet.java
     $ java -classpath ../MyLibrary.jar MyApp.java

3. A program that wants to ensure the use of a specific language version

     $ java --source 10 HelloJDK10.java
     $ java --source=10 HelloJDK10.java


4. A shebang script in an otherwise normal source file. The example 
shows that you
     do not need a --source option in a shebang file that follows the 
normal naming conventions
     for a source file.

     First line of HelloShebang.java
         #!/usr/bin/java

     The file can be executed with
         $ ./HelloShebang.java a b c

     The effect of this line is to execute
         /usr/bin/java HelloShebang.java a b c


5. A shebang script that is named as a typical command might be named

     First line of a file called myScript

         #!/usr/bin/java --script 10

     The file can be executed with

         $ ./myScript a b c

     The effect of this line is to execute the following, using quotes 
to indicate the arg provided by
     the OS shebang mechanism

         /usr/bin/java '--script 10' ./myScript a b c

     ... which will be treated by the launcher as equivalent to (note no 
quotes)

         /usr/bin/java --script 10 ./myScript a b c


6. A shebang script that uses additional VM options

     First line of a file called myScript

         #!/usr/bin/java --script 10  --classpath /home/my/lib/utils.jar 
-Xmx1024m

     The file can be executed with

         $ ./myScript a b c

     The effect of this line is to execute the following, using quotes 
to indicate the arg provided by
     the OS shebang mechanism

         /usr/bin/java '--script 10  --classpath /home/my/lib/utils.jar 
-Xmx1024m' ./myScript a b c

     ... which will be treated by the launcher as equivalent to (note no 
quotes)

         /usr/bin/java --script 10  --classpath /home/my/lib/utils.jar 
-Xmx1024m ./myScript a b c


Note that a corollary of the proposed change is that if any arguments 
for the Java launcher are
provided in a shebang file, then the --source option should be used, and 
should be appear as the
first option after the name of the executable. This is avoid more 
complex rules about dealing
with whitespace in any other options.  This seems like an appropriate 
and reasonable compromise.

-- Jon