symlink aliases instead of copying them on POSIX

Author: Largo

README.md

@@ -69,66 +69,57 @@ dependencies (gems and DLLs) into an executable named
 
     ocran --help
 
-Ocran options:
+#### Ocran options:
 
-    --help             Display this information.
-    --quiet            Suppress output while building executable.
-    --verbose          Show extra output while building executable.
-    --version          Display version number and exit.
+* `--help`: Display available command-line options and information.
+* `--quiet`: Suppress all output during the build process.
+* `--verbose`: Provide detailed output during the build process, useful for debugging.
+* `--version`: Display the version number of OCRAN and exit.
 
-Packaging options:
+#### Packaging options:
 
-    --dll dllname      Include additional DLLs from the Ruby bindir.
-    --add-all-core     Add all core ruby libraries to the executable.
-    --gemfile <file>   Add all gems and dependencies listed in a Bundler Gemfile.
-    --no-enc           Exclude encoding support files
+* `--dll <dllname>`: Include additional DLLs from the Ruby `bin` directory.
+* `--add-all-core`: Add all standard Ruby core libraries to the executable.
+* `--gemfile <file>`: Include all gems and their dependencies listed in a specified Bundler `Gemfile`.
+* `--no-enc`: Exclude encoding support files to reduce the size of the executable.
 
-Gem content detection modes:
+#### Gem content detection modes:
 
-    --gem-minimal[=gem1,..]  Include only loaded scripts
-    --gem-guess=[gem1,...]   Include loaded scripts & best guess (DEFAULT)
-    --gem-all[=gem1,..]      Include all scripts & files
-    --gem-full[=gem1,..]     Include EVERYTHING
-    --gem-spec[=gem1,..]     Include files in gemspec (Does not work with Rubygems 1.7+)
+These options control which files from the included gems are added to the executable.
 
-    --[no-]gem-scripts[=..]  Other script files than those loaded
-    --[no-]gem-files[=..]    Other files (e.g. data files)
-    --[no-]gem-extras[=..]   Extra files (README, etc.)
+* `--gem-minimal[=gem1,..]`: Include only the scripts that are actually loaded during the dependency run.
+* `--gem-guess[=gem1,..]`: Include loaded scripts and a "best guess" of other necessary files (DEFAULT).
+* `--gem-all[=gem1,..]`: Include all scripts and important files from the gem.
+* `--gem-full[=gem1,..]`: Include every single file found in the gem's directory.
+* `--gem-spec[=gem1,..]`: Include files listed in the gem's gemspec (Note: Compatibility issues with newer RubyGems).
 
-Gem modes:
+You can also fine-tune content inclusion using these flags:
 
-* *minimal*: loaded scripts
-* *guess*: loaded scripts and other files
-* *all*: loaded scripts, other scripts, other files (except extras)
-* *full*: Everything found in the gem directory
+* `--[no-]gem-scripts[=..]`: Include/exclude non-loaded script files (.rb, .rbw).
+* `--[no-]gem-files[=..]`: Include/exclude other files like data files.
+* `--[no-]gem-extras[=..]`: Include/exclude "extra" files like READMEs, tests, and C sources.
 
-File groups:
+#### Auto-detection options:
 
-* *scripts*: .rb/.rbw files  
-* *extras*: C/C++ sources, object files, test, spec, README  
-* *files*: all other files  
+* `--no-dep-run`: Do not run the source script to check for dependencies. Use this if your script has side effects during load or if you are manually specifying all dependencies.
+* `--no-autoload`: Do not attempt to load or include `autoload`ed constants.
+* `--no-autodll`: Disable the automatic detection of runtime DLL dependencies.
 
-Auto-detection options:
+#### Output options:
 
-    --no-dep-run       Don't run script.rb to check for dependencies.
-    --no-autoload      Don't load/include script.rb's autoloads.
-    --no-autodll       Disable detection of runtime DLL dependencies.
+* `--output <file>`: Specify the name and path of the generated executable. Defaults to `./<scriptname>.exe`.
+* `--no-lzma`: Disable LZMA compression. This results in faster build times but a significantly larger executable.
+* `--innosetup <file>`: Use the specified Inno Setup script (.iss) to create a Windows installer instead of a single standalone executable.
 
-Output options:
+#### Executable options:
 
-    --output <file>    Name the exe to generate. Defaults to ./<scriptname>.exe.
-    --no-lzma          Disable LZMA compression of the executable.
-    --innosetup <file> Use given Inno Setup script (.iss) to create an installer.
-
-Executable options:
-
-    --windows          Force Windows application (rubyw.exe)  
-    --console          Force console application (ruby.exe)  
-    --chdir-first      When exe starts, change working directory to app dir.  
-    --icon <ico>       Replace icon with a custom one.  
-    --rubyopt <str>    Set the RUBYOPT environment variable when running the executable
-    --debug            Executable will be verbose.  
-    --debug-extract    Executable will unpack to local dir and not delete after.  
+* `--windows`: Force the creation of a Windows GUI application (uses `rubyw.exe`).
+* `--console`: Force the creation of a console application (uses `ruby.exe`).
+* `--chdir-first`: Changes the working directory to the application's temporary extraction directory before the script starts.
+* `--icon <ico>`: Replace the default Ruby icon with a custom `.ico` file.
+* `--rubyopt <str>`: Set the `RUBYOPT` environment variable that will be used when the executable runs.
+* `--debug`: Enables verbose output when the generated executable is run.
+* `--debug-extract`: The executable will unpack its contents to a local directory and will not delete them after execution, which is helpful for troubleshooting extraction issues.
 
 
 ### Compilation:

exe/ocran

@@ -42,6 +42,11 @@ def copy_to_bin(source, target)
       cp(source, BINDIR / target)
     end
 
+    def symlink_in_bin(target, link_name)
+      verbose "symlink #{BINDIR / link_name} -> #{target}"
+      symlink(BINDIR / link_name, target.to_s)
+    end
+
     def copy_to_gem(source, target)
       cp(source, GEMDIR / target)
     end

lib/ocran/build_helper.rb

@@ -150,10 +150,10 @@ def construct(builder)
         libruby_src = Gem.win_platform? ? bindir / libruby_so : libdir / libruby_so
         builder.copy_to_bin(libruby_src, libruby_so)
 
-        # On POSIX systems, we also need to copy symlinks (aliases) for libruby.so
+        # On POSIX systems, create symlinks (aliases) for libruby.so
         unless Gem.win_platform?
           libruby_aliases.each do |libruby_alias|
-            builder.copy_to_bin(libdir / libruby_alias, libruby_alias)
+            builder.symlink_in_bin(libruby_so, libruby_alias)
           end
         end
       end

lib/ocran/direction.rb

@@ -13,6 +13,7 @@ class StubBuilder
     OP_CREATE_FILE = 2
     OP_SETENV = 3
     OP_SET_SCRIPT = 4
+    OP_CREATE_SYMLINK = 5
 
     DEBUG_MODE          = 0x01
     EXTRACT_TO_EXE_DIR  = 0x02
@@ -154,6 +155,12 @@ def mkdir(target)
       write_path(target)
     end
 
+    def symlink(link_path, target)
+      write_opcode(OP_CREATE_SYMLINK)
+      write_path(link_path)
+      write_string(target.to_s)
+    end
+
     def cp(source, target)
       unless File.exist?(source)
         raise "The file does not exist (#{source})"

lib/ocran/stub_builder.rb

@@ -1,5 +1,9 @@
 #include <stdlib.h>
 #include <string.h>
+#ifndef _WIN32
+#include <unistd.h>
+#include <errno.h>
+#endif
 #include "error.h"
 #include "system_utils.h"
 #include "inst_dir.h"
@@ -263,6 +267,53 @@ bool ExportFileToInstDir(const char *rel_path, const void *buf, size_t len)
     return result;
 }
 
+#ifndef _WIN32
+bool CreateSymlinkUnderInstDir(const char *rel_link_path, const char *target)
+{
+    if (!IsInstDirSet()) {
+        APP_ERROR("Installation directory has not been set");
+        return false;
+    }
+
+    if (!rel_link_path || !*rel_link_path) {
+        APP_ERROR("rel_link_path is NULL or empty");
+        return false;
+    }
+
+    if (!target || !*target) {
+        APP_ERROR("target is NULL or empty");
+        return false;
+    }
+
+    char *link_path = ExpandInstDirPath(rel_link_path);
+    if (!link_path) {
+        return false;
+    }
+
+    bool result = false;
+    char *parent = GetParentPath(link_path);
+    if (parent && *parent && !CreateDirectoriesRecursively(parent)) {
+        APP_ERROR("Failed to create parent directory for symlink '%s'", link_path);
+        goto cleanup;
+    }
+
+    if (symlink(target, link_path) < 0) {
+        APP_ERROR("Failed to create symlink '%s' -> '%s': %s", link_path, target, strerror(errno));
+        goto cleanup;
+    }
+
+    DEBUG("CreateSymlinkUnderInstDir: '%s' -> '%s'", link_path, target);
+    result = true;
+
+cleanup:
+    if (parent) {
+        free(parent);
+    }
+    free(link_path);
+    return result;
+}
+#endif /* _WIN32 */
+
 bool SetEnvWithInstDir(const char *name, const char *value)
 {
     char *replaced_value = ReplaceInstDirPlaceholder(value);

src/inst_dir.c

@@ -141,3 +141,17 @@ bool ExportFileToInstDir(const char *rel_path, const void *buf, size_t len);
  * @return true on success; false on failure.
  */
 bool SetEnvWithInstDir(const char *name, const char *value);
+
+/**
+ * @brief Create a symlink under the installation directory (POSIX only).
+ *
+ * Creates a symbolic link at rel_link_path that points to target.
+ * Both paths are relative to the installation directory.
+ * The target is treated as a bare filename within the same directory.
+ *
+ * @param rel_link_path  Relative path for the new symlink (e.g. "bin/libruby.so").
+ * @param target         Symlink target filename (e.g. "libruby.so.3.2.0").
+ *
+ * @return true on success; false on failure.
+ */
+bool CreateSymlinkUnderInstDir(const char *rel_link_path, const char *target);

src/inst_dir.h

@@ -153,6 +153,22 @@ static bool process_opcode(UnpackReader *reader, Opcode opcode)
             return SetScriptInfo(args, size);
         }
 
+        case OP_CREATE_SYMLINK: {
+            if (!read_string(reader, &name)) {
+                return false;
+            }
+            if (!read_string(reader, &value)) {
+                return false;
+            }
+            DEBUG("OP_CREATE_SYMLINK: link='%s', target='%s'", name, value);
+#ifndef _WIN32
+            return CreateSymlinkUnderInstDir(name, value);
+#else
+            DEBUG("OP_CREATE_SYMLINK: skipped on Windows");
+            return true;
+#endif
+        }
+
         default: {
             DEBUG("Invalid opcode: %d", opcode);
             return false;

src/unpack.c

@@ -5,6 +5,7 @@ typedef enum {
     OP_CREATE_FILE      = 2,
     OP_SETENV           = 3,
     OP_SET_SCRIPT       = 4,
+    OP_CREATE_SYMLINK   = 5,
 } Opcode;
 
 /**