Ruby Sourcefiles and Libraries

Ruby applications can be comprised of multiple Ruby sourcefiles, and they can access objects made available by Ruby libraries.

Ruby has a very simple mechanism to support this - Ruby code can use APIs to load and execute other Ruby files. These other files then may perform tasks, such as creating classes, modules, methods and constants. Once the loaded file completes executing, the original Ruby code resumes and it can use the objects that were created.

In addition, there are API methods such as require which will load (and execute) a file, but then if the file is require'd again it will not reload the file. This is so multiple sourcefiles can "require" that a certain file be loaded, and the effect will be that the file is only loaded once. It is typical for Ruby sourcefiles to begin with require method calls, effectively declaring what other files need to be loaded as a prerequisite.

There are 2 types of file that can be loaded in Ruby:

• a Ruby sourcefile, whose name must end in ".rb"
• a Ruby extension library, whose name must end with ".dll" on Windows platforms or ".so" on everything else. These components are typically written in C, conform to certain requirements for Ruby extension libraries, and when executed perform tasks (such as creating objects in the Ruby environment) using the Ruby C API - creating extension libraries is beyond the scope of this document.

A basic multi-file Ruby application therefore consists of a designated initial sourcefile, which is to be executed directly and is called the "main" sourcefile, and some other Ruby sourcefiles which are loaded in the course of executing the initial file (usually via require or related APIs).

A basic Ruby library consists of some Ruby sourcefiles or extension libraries that are intended to be require'd in order to enable their features, and perhaps some other sourcefiles that are loaded in the course of the library files' execution. Ruby has a "standard library" with this structure, which is pre-installed with Ruby.

Load file name resolution

Ruby resolves load file names very similarly to the way that command-line commands are resolved in unix or Windows environments.

There exists a Ruby "load path" which is a list of filesystem directories to be potentially searched when loading a file. The load path is defined in various ways when the Ruby environment is started up (e.g. via hard-coded paths, command-line switches and environment variables). There exist no core APIs to modify a load path during Ruby execution, although a library extension could provide such features.

Load file names (and, for that matter, load path names) may be absolute or relative filesystem paths as supported by the underlying operating system, including UNC paths and NTFS streams in Windows environments. The "standard" resolution procedure for load file names is as follows:

• If the file name is an absolute path, it resolves directly
• Otherwise, if it is explicitly relative to the current working directory (i.e. its first path element is "." or ".."), it is resolved against the current working directory
• Otherwise, resolution is attempted against each load path in turn until an openable file is found.

If load path names are relative (even explicitly), they are resolved against the current working directory.

Some APIs (e.g. require) permit you to leave the file extension off the load file name, and they will search for matching files with ".rb" (by preference) or ".dll"/".so" extensions.

There exist the usual complications on Windows - relative paths specifying a drive letter (e.g. D:file.rb) are relative the current working directory on that drive or potentially load paths on that drive, and relative paths beginning with a "" or "/" are relative to the current working drive or a load path's drive or UNC share.

On Windows environments, paths may use "/" interchangeably with "", and load file names ending in ".so" will also search for ".dll" files. Therefore, it is recommended to use "/" and ".so" rather than "" and ".dll" for portability with non-Windows platforms.

Some APIs (e.g. require_relative) can resolve a load file name relative to the location of the currently executing Ruby sourcefile.

Executing Ruby sourcefiles

When a Ruby sourcefile is loaded (other than the main sourcefile) its execution context is similar to that of the main sourcefile, except that it has its own local variable context. A sourcefile can also be loaded with a "wrap=true" option which modifies its self and class reference stack. See the Execution Context section for details.

Require

• Canonicalizing
• Locking

Ruby C API extensions

• require RB
• require SO

API

• to_path()