CompilerPackagingAndPathing

pfussell edited this page Jan 6, 2011 · 4 revisions

» JRuby Project Wiki Home Page       » Design: Internals

Compiler Packaging and Pathing

This is the packaging and pathing specification for JRuby compiler.

Given:

  • A baz.rb file exists in some directory foo/bar, which exists under user's home directory.
Requirements:
  • Compilation of baz.rbshould produce baz.class in the same location.
  • Java's requirement for unique class names means baz.class must have a unique class name.
  • baz.class may be executed from locations other than the one from which it was compiled.
So assume baz.class contains a class named foo.bar.baz, existing under <home>/foo/bar.
  • Load path contains &lt;home&gt;.
  • Executing require 'foo/bar/baz' should pick up the class file and load it.
  • Executing jruby foo/bar/baz.class should execute it correctly.
  • Executing jruby -e "require 'baz'" from within &lt;home&gt;/foo/bar should pick it up correctly.
Load path locations are typically expected by the source; requires and such depend on their being correct. If the load path points at &lt;home&gt; normally, pointing it at &lt;home&gt;/foo instead would likely cause requires in baz to fail. So:
  • We can reasonably expect that the load path structure is a good representation of a unique class name, and that execution would not expect something more unique.
  • Therefore, a subpath within the load path is a good enough indicator of package for the compiled class.
  • However, load path searching should still be done. If we switch to foo/bar and try to require baz, it should continue to load. If we try to run baz directly, it should continue to load.
  • Therefore, we should continue to use load path searching as the primary mechanism for finding the compiled class file.
  • Therefore, we should also examine the class file directly for the contained class name, rather than expecting it to match package structure.
Given that compilation may happen from any arbitrary directory:

We need a way to determine the appropriate load path for a file under compilation. Because load paths may differ at runtime for the script/app in question, we should do three things:

  • Provide a command-line means to specify the base dir from which the source is being compiled. This is similar to the requirement in .java files to specify a host dir that represents the "root" of the path.
  • Default to current directory as the "root" of the path, if the filename to be compiled does not contain relative path modifiers and is a subpath under the current directory.
  • If no base is given and there are relative modifiers in the full file path, generate a package name based on the full canonical filename. Perhaps print a warning.
Addendums:
  • For any given file that must use a canonical path containing a device name to generate package name, the device indicator (C:\, \\somehost\, etc.) will be considered the root and omitted from the resulting package.
A few cases:

1. Simple Case

current dir: C:\home
file to compile: C:\home\foo\bar\baz.rb, specified as foo\bar\baz.rb
no basedir specified
  • filename given has no relative modifiers
  • filename is within a subpath of current directory
  • package generated is foo.bar
  • baz.class file is placed in C:\home\foo\bar\baz.class
2. Second Case
current dir: C:\home2
file to compile: C:\home\foo\bar\baz.rb, specified as ..\home\foo\bar\baz.rb
no basedir specified
  • filename has relative elements
  • canonical path is C:\home\foo\bar\baz.rb
  • package generated is home.foo.bar
3. Third Case
current dir: C:\home2
file to compile: C:\home\foo\bar\baz.rb, specified asC:\home\foo\bar\baz.rb
basedir: C:\home
  • basedir is specified
  • target file is in a subpath of basedir with no relative modifiers
  • package and result same as in (1) Simple Case above
Execution cases that should succeed in loading a baz.class, given any of the results above

Case 1

load path contains C:\home
jruby -e "require 'baz'"
Case 2
load path contains C:\home2
current dir is C:\home2
jruby -e "require '../home/foo/bar/baz'"
Case 3
current dir is C:\home2
jruby ../home/foo/bar/baz.class
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.