{"id":13533275,"url":"https://github.com/larsch/ocra","last_synced_at":"2025-04-01T21:32:09.226Z","repository":{"id":548179,"uuid":"178300","full_name":"larsch/ocra","owner":"larsch","description":"One-Click Ruby Application Builder","archived":false,"fork":false,"pushed_at":"2023-12-27T02:54:56.000Z","size":504,"stargazers_count":832,"open_issues_count":73,"forks_count":83,"subscribers_count":37,"default_branch":"master","last_synced_at":"2024-05-21T13:58:08.946Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://ocra.rubyforge.org/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/larsch.png","metadata":{"files":{"readme":"README.md","changelog":"History.txt","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2009-04-17T07:47:33.000Z","updated_at":"2024-05-18T11:26:26.000Z","dependencies_parsed_at":"2022-07-07T16:37:43.437Z","dependency_job_id":"251413d1-b8d4-4d48-a839-48334fb308fc","html_url":"https://github.com/larsch/ocra","commit_stats":{"total_commits":320,"total_committers":11,"mean_commits":29.09090909090909,"dds":0.365625,"last_synced_commit":"893fe8821af9986357bfc8d6c0101ce34ccb5c10"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larsch%2Focra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larsch%2Focra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larsch%2Focra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larsch%2Focra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/larsch","download_url":"https://codeload.github.com/larsch/ocra/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246713328,"owners_count":20821874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T07:01:18.267Z","updated_at":"2025-04-01T21:32:08.753Z","avatar_url":"https://github.com/larsch.png","language":"Ruby","readme":"# ocra\n\nhome   :: https://github.com/larsch/ocra/\n\nissues :: http://github.com/larsch/ocra/issues\n\nforum  :: http://groups.google.com/group/ruby-ocra\n\n## Description\n\nOCRA (One-Click Ruby Application) builds Windows executables from Ruby\nsource code. The executable is a self-extracting, self-running\nexecutable that contains the Ruby interpreter, your source code and\nany additionally needed ruby libraries or DLL.\n\n## Features\n\n* LZMA Compression (optional, default on)\n* Both windowed/console mode supported\n* Includes gems based on usage, or from a Bundler Gemfile\n\n## Problems \u0026 Bug Reporiting\n\n* Windows support only\n\nIf you experience problems with OCRA or have found a bug, please use\nthe issue tracker on GitHub (http://github.com/larsch/ocra/issues).\nYou can also join the Google Group discussion forum to ask questions\nand get help (http://groups.google.com/group/ruby-ocra).\n\n## Installation\n\nGem:\n\n    gem install ocra\n\nAlternatively you can download the gem at either\nhttp://rubygems.org/gems/ocra or\nhttps://github.com/larsch/ocra/releases/.\n\nStand-alone Version: Get ocrasa.rb from\nhttps://github.com/larsch/ocra/releases/. Requires nothing but a\nworking Ruby installation on Windows.\n\n## Synopsis\n\n### Building an executable:\n\n    ocra script.rb\n\nWill package `script.rb`, the Ruby interpreter and all\ndependencies (gems and DLLs) into an executable named\n`script.exe`.\n\n### Command line:\n  \n    ocra [options] script.rb [\u003cother files\u003e ...] [-- \u003cscript arguments\u003e ...]\n\n### Options:\n\n    ocra --help\n\nOcra options:\n\n    --help             Display this information.\n    --quiet            Suppress output while building executable.\n    --verbose          Show extra output while building executable.\n    --version          Display version number and exit.\n\nPackaging options:\n\n    --dll dllname      Include additional DLLs from the Ruby bindir.\n    --add-all-core     Add all core ruby libraries to the executable.\n    --gemfile \u003cfile\u003e   Add all gems and dependencies listed in a Bundler Gemfile.\n    --no-enc           Exclude encoding support files\n\nGem content detection modes:\n\n    --gem-minimal[=gem1,..]  Include only loaded scripts\n    --gem-guess=[gem1,...]   Include loaded scripts \u0026 best guess (DEFAULT)\n    --gem-all[=gem1,..]      Include all scripts \u0026 files\n    --gem-full[=gem1,..]     Include EVERYTHING\n    --gem-spec[=gem1,..]     Include files in gemspec (Does not work with Rubygems 1.7+)\n\n    --[no-]gem-scripts[=..]  Other script files than those loaded\n    --[no-]gem-files[=..]    Other files (e.g. data files)\n    --[no-]gem-extras[=..]   Extra files (README, etc.)\n\nGem modes:\n\n* *minimal*: loaded scripts\n* *guess*: loaded scripts and other files\n* *all*: loaded scripts, other scripts, other files (except extras)\n* *full*: Everything found in the gem directory\n\nFile groups:\n\n* *scripts*: .rb/.rbw files  \n* *extras*: C/C++ sources, object files, test, spec, README  \n* *files*: all other files  \n\nAuto-detection options:\n\n    --no-dep-run       Don't run script.rb to check for dependencies.\n    --no-autoload      Don't load/include script.rb's autoloads.\n    --no-autodll       Disable detection of runtime DLL dependencies.\n\nOutput options:\n\n    --output \u003cfile\u003e    Name the exe to generate. Defaults to ./\u003cscriptname\u003e.exe.\n    --no-lzma          Disable LZMA compression of the executable.\n    --innosetup \u003cfile\u003e Use given Inno Setup script (.iss) to create an installer.\n\nExecutable options:\n\n    --windows          Force Windows application (rubyw.exe)  \n    --console          Force console application (ruby.exe)  \n    --chdir-first      When exe starts, change working directory to app dir.  \n    --icon \u003cico\u003e       Replace icon with a custom one.  \n    --debug            Executable will be verbose.  \n    --debug-extract    Executable will unpack to local dir and not delete after.  \n\n  \n### Compilation:\n\n* OCRA will load your script (using `Kernel#load`) and build\n  the executable when it exits.\n\n* Your program should 'require' all necessary files when invoked without\n  arguments, so OCRA can detect all dependencies.\n\n* DLLs are detected automatically but only those located in your Ruby\n  installation are included.\n\n* .rb files will become console applications. .rbw files will become\n  windowed application (without a console window popping\n  up). Alternatively, use the `--console` or\n  `--windows` options.\n\n### Running your application:\n\n* The 'current working directory' is not changed by OCRA when running\n  your application. You must change to the installation or temporary\n  directory yourself. See also below.\n* When the application is running, the OCRA_EXECUTABLE environment\n  variable points to the .exe (with full path).\n* The temporary location of the script can be obtained by inspected\n  the $0 variable.\n* OCRA does not set up the include path. Use `$:.unshift\n  File.dirname($0)` at the start of your script if you need to\n  'require' additional source files from the same directory as your\n  main script.\n\n### Pitfalls:\n\n* Avoid modifying load paths at run time. Specify load paths using -I\n  or RUBYLIB if you must, but don't expect OCRA to preserve them for\n  runtime. OCRA may pack sources into other directories than you\n  expect.\n* If you use .rbw files or the `--windows` option, then check\n  that your application works with rubyw.exe before trying with OCRA.\n* Avoid absolute paths in your code and when invoking OCRA.\n\n## REQUIREMENTS:\n\n* Windows\n* Working Ruby installation.\n* MinGW Installation (when working with the source code only)\n\n### Stand-alone version\n\nGet ocrasa.rb from http://rubyforge.org/frs/?group_id=8185. Requires\nnothing but a working Ruby installation on Windows.\n\n## Technical details\n\nOCRA first runs the target script in order to detect any files that\nare loaded and used at runtime (Using `Kernel#require` and\n`Kernel#load`).\n\nOCRA embeds everything needed to run a Ruby script into a single\nexecutable file. The file contains the .exe stub which is compiled\nfrom C-code, and a custom opcode format containing instructions to\ncreate directories, save files, set environment variables and run\nprograms. The OCRA script generates this executable and the\ninstructions to be run when it is launched.\n\nWhen executed, the OCRA stub extracts the Ruby interpreter and your\nscripts into a temporary directory. The directory will contains the\nsame directory layout as your Ruby installlation. The source files for\nyour application will be put in the 'src' subdirectory.\n\n### Libraries\n\nAny code that is loaded through `Kernel#require` when your\nscript is executed will be included in the OCRA\nexecutable. Conditionally loaded code will not be loaded and included\nin the executable unless the code is actually run when OCRA invokes\nyour script. Otherwise, OCRA won't know about it and will not include\nthe source files.\n\nRubyGems are handled specially. Whenever a file from a Gem is\ndetected, OCRA will attempt to include all the required files from\nthat specific Gem, expect some unlikely needed files such as readme's\nand other documentation. This behaviour can be controlled by using the\n--gem-* options. Behaviour can be changed for all gems or specific\ngems using --gem-*=gemname.\n\nLibraries found in non-standard path (for example, if you invoke OCRA\nwith \"ruby -I some/path\") will be placed into the site dir\n(lib/ruby/site_ruby). Avoid changing `$LOAD_PATH` or\n`$:` from your script to include paths outside your source\ntree, since OCRA may place the files elsewhere when extracted into the\ntemporary directory.\n\nIn case your script (or any of its dependencies) sets up autoloaded\nmodule using `Kernel#autoload`, OCRA will automatically try to\nload them to ensure that they are all included in the\nexecutable. Modules that doesn't exist will be ignored (a warning will\nbe logged).\n\nDynamic link libraries (.dll files, for example WxWidgets, or other\nsource files) will be detected and included by OCRA.\n\n### Including libraries non-automatically\n\nIf an application or framework is complicated enough that it tends\nto confuse Ocra's automatic dependency resolution, then you can\nuse other means to specify what needs to be packaged with your app.\n\nTo disable automatic dependency resolution, use the `--no-dep-run`\noption; with it, Ocra will skip executing your program during the\nbuild process. This on the other hand requires using `--gem-full` option\n(see more below); otherwise Ocra will not include all the necessary\nfiles for the gems.\n\nYou will also probably need to use the `--add-all-core` option to\ninclude the Ruby core libraries.\n\nIf your app uses gems, then you can specify them in a\nBundler (http://gembundler.com) Gemfile, then use the --gemfile\noption to supply it to Ocra. Ocra will automatically include all\ngems specified, and all their dependencies.\n\n(Note: This assumes that the gems are installed in your system,\n*not* locally packaged inside the app directory by \"bundle package\")\n\nThese options are particularly useful for packaging Rails\napplications.  For example, to package a Rails 3 app in the\ndirectory \"someapp\" and create an exe named \"someapp.exe\", without\nactually running the app during the build, you could use the\nfollowing command:\n\n    ocra someapp/script/rails someapp --output someapp.exe --add-all-core \\\n    --gemfile someapp/Gemfile --no-dep-run --gem-full --chdir-first -- server\n\nNote the space between `--` and `server`! It's important; `server` is\nan argument to be passed to rails when the script is ran.\n\nRails 2 apps can be packaged similarly, though you will have to\nintegrate them with Bundler (http://gembundler.com/rails23.html)\nfirst.\n\n### Gem handling\n\nBy default, Ocra includes all scripts that are loaded by your script\nwhen it is run before packaging. Ocra detects which gems are using and\nincludes any additional non-script files from those gems, except\ntrivial files such as C/C++ source code, object files, READMEs, unit\ntests, specs, etc.\n\nThis behaviour can be changed by using the --gem-* options. There are\nfour possible modes:\n\n* *minimal*: Include only loaded scripts\n* *guess*: Include loaded scripts and important files (DEFAULT)\n* *all*: Include all scripts and important files\n* *full*: Include all files\n\nIf you find that files are missing from the resulting executable, try\nfirst with --gem-all=gemname for the gem that is missing, and if that\ndoes not work, try --gem-full=gemname. The paranoid can use --gem-full\nto include all files for all required gems.\n\n### Creating an installer for your application\n\nTo make your application start up quicker, or to allow it to\nkeep files in its application directory between runs, or if\nyou just want to make your program seem more like a \"regular\"\nWindows application, you can have Ocra generate an installer\nfor your app with the free Inno Setup software.\n\nYou will first have to download and install Inno Setup 5 or\nlater, and also add its directory to your PATH (so that Ocra\ncan find the ISCC compiler program). Once you've done that,\nyou can use the `--innosetup` option to Ocra to supply an\nInno Setup script. Do not add any [Files] or [Dirs] sections\nto the script; Ocra will figure those out itself.\n\nTo continue the Rails example above, let's package the Rails 3\napp into an installer. Save the following as `someapp.iss`:\n\n  [Setup]\n  AppName=SomeApp\n  AppVersion=0.1\n  DefaultDirName={pf}\\SomeApp\n  DefaultGroupName=SomeApp\n  OutputBaseFilename=SomeAppInstaller\n\n  [Icons]\n  Name: \"{group}\\SomeApp\"; Filename: \"{app}\\someapp.exe\"\n  Name: \"{group}\\Uninstall SomeApp\"; Filename: \"{uninstallexe}\"\n\nThen, run Ocra with this command:\n\n    ocra someapp/script/rails someapp --output someapp.exe --add-all-core \\\n    --gemfile someapp/Gemfile --no-dep-run --gem-full --chdir-first --no-lzma \\\n    --innosetup someapp.iss -- server\n\nIf all goes well, a file named \"SomeAppInstaller.exe\" will be placed\ninto the Output directory.\n\n### Environment variables\n\nOCRA executables clear the RUBYLIB environment variable before your\nscript is launched. This is done to ensure that your script does not\nuse load paths from the end user's Ruby installation.\n\nOCRA executables set the RUBYOPT environment variable to the value it\nhad when you invoked OCRA. For example, if you had \"RUBYOPT=rubygems\"\non your build PC, OCRA ensures that it is also set on PC's running the\nexecutables.\n\nOCRA executables set OCRA_EXECUTABLE to the full path of the\nexecutable, for example\n\n    ENV[\"OCRA_EXECUTABLE\"] # =\u003e C:\\Program Files\\MyApp\\MyApp.exe\n\n### Working directory\n\nThe OCRA executable does not change the working directory when it is\nlaunched, unless you use the `--chdir-first` option.\n\nYou should not assume that the current working directory when invoking\nan executable built with .exe is the location of the source script. It\ncan be the directory where the executable is placed (when invoked\nthrough the Windows Explorer), the users' current working directory\n(when invoking from the Command Prompt), or even\n`C:\\\\WINDOWS\\\\SYSTEM32` when the executable is invoked through\na file association.\n\nWith the `--chdir-first` option, the working directory will\nalways be the common parent directory of your source files. This\nshould be fine for most applications. However, if your application\nis designed to run from the command line and take filenames as\narguments, then you cannot use this option.\n\nIf you wish to maintain the user's working directory, but need to\n`require` additional Ruby scripts from the source directory, you can\nadd the following line to your script:\n\n    $LOAD_PATH.unshift File.dirname($0)\n\n### Load path mangling\n\nAdding paths to `$LOAD_PATH` or `$:` at runtime is not\nrecommended. Adding relative load paths depends on the working\ndirectory being the same as where the script is located (See\nabove). If you have additional library files in directories below the\ndirectory containing your source script you can use this idiom:\n\n    $LOAD_PATH.unshift File.join(File.dirname($0), 'path/to/script')\n\n### Detecting\n\nYou can detect whether OCRA is currently building your script by\nlooking for the 'Ocra' constant. If it is defined, OCRA is currenly\nbuilding the executable from your script. For example, you can use\nthis to avoid opening a GUI window when compiling executables:\n\n    app = MyApp.new\n    app.main_loop unless defined?(Ocra)\n\n### Additional files and resources\n\nYou can add additional files to the OCRA executable (for example\nimages) by appending them to the command line. They should be placed\nin the source directory with your main script (or a subdirectory).\n\n    ocra mainscript.rb someimage.jpeg docs/document.txt\n\nThis will create the following layout in the temporary directory when\nyour program is executed:\n\n    src/mainscript.rb\n    src/someimage.jpeg\n    src/docs/document.txt\n\nBoth files, directoriess and glob patterns can be specified on the\ncommand line. Files will be added as-is. If a directory is specified,\nOCRA will include all files found below that directory. Glob patterns\n(See Dir.glob) can be used to specify a specific set of files, for\nexample:\n\n    ocra script.rb assets/**/*.png\n\n### Command Line Arguments\n\nTo pass command line argument to your script (both while building and\nwhen run from the resulting executable), specify them after a\n`--` marker. For example:\n\n    ocra script.rb -- --some-options=value\n\nThis will pass `--some-options=value` to the script when\nbuild and when running the executable. Any extra argument specified by\nthe user when invoking the executable will be appended after the\ncompile-time arguments.\n\n### Window/Console\n\nBy default, OCRA builds console application from .rb-files and\nwindowed applications (without console window) from .rbw-files.\n\nRuby on Windows provides two executables: ruby.exe is a console mode\napplication and rubyw.exe is a windowed application which does not\nbring up a console window when launched using the Windows Explorer.\nBy default, or if the `--console` option is used, OCRA will\nuse the console runtime (ruby.exe). OCRA will automatically select the\nwindowed runtime when your script has the \".rbw\" extension, or if you\nspecify the `--windows` command line option.\n\nIf your application works in console mode but not in windowed mode,\nfirst check if your script works without OCRA using rubyw.exe. A\nscript that prints to standard output (using puts, print etc.) will\neventually cause an exception when run with rubyw.exe (when the IO\nbuffers run full).\n\nYou can also try wrapping your script in an exception handler that\nlogs any errors to a file:\n\n    begin\n      # your script here\n    rescue Exception =\u003e e\n      File.open(\"except.log\") do |f|\n        f.puts e.inspect\n        f.puts e.backtrace\n      end\n    end\n\n## CREDITS:\n\nThanks for Igor Pavlov for the LZMA compressor and decompressor. The\nsource code used was place into Public Domain by Igor Pavlov.\n\nErik Veenstra for rubyscript2exe which provided inspiration.\n\nDice for the default .exe icon (vit-ruby.ico,\nhttp://ruby.morphball.net/vit-ruby-ico_en.html)\n\n## LICENSE:\n\n(The MIT License)\n\nCopyright (c) 2009-2020 Lars Christensen\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n'Software'), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","funding_links":[],"categories":["Awesome Ruby CLIs","Ruby"],"sub_categories":["Release"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarsch%2Focra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flarsch%2Focra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarsch%2Focra/lists"}