:toc: macro :toclevels: 5 :figure-caption!: :bundler_inline_link: link:https://alchemists.io/articles/ruby_bundler_inline[Bundler Inline] :development_containers_link: link:https://containers.dev[Development Containers] :docker_link: link:https://www.docker.com[Docker] :gemsmith_link: link:https://alchemists.io/projects/gemsmith[Gemsmith] :string_formats_link: link:https://docs.ruby-lang.org/en/3.3/format_specifications_rdoc.html[String Formats] = Rubysmith Rubysmith is a command line interface for smithing Ruby projects. This gem is useful in situations in which you need something more sophisticated than a {bundler_inline_link} script but less than a {gemsmith_link} gem. Rubysmith is the foundation of Gemsmith and provides much of the same functionality as Gemsmith but is solely tailored for pure Ruby projects. Again, this is a great tool for spiking quick Ruby implementations, sharing code snippets with others, or building full blown Ruby projects for collaboration with others. toc::[] == Features * Builds a Ruby project skeleton for custom design and development. * Uses link:https://alchemists.io/projects/runcom[Runcom] for resource configuration management. * Uses link:https://alchemists.io/projects/pragmater[Pragmater] for Ruby source pragma directives. * Supports link:https://github.com/amazing-print/amazing_print[Amazing Print]. * Supports link:https://alchemists.io/projects/caliber[Caliber]. * Supports link:https://circleci.com[Circle CI]. * Supports link:https://orcid.org[Citations (ORCID)]. * Supports console script for local development. * Supports link:https://github.com/ruby/debug[Debug]. * Supports {development_containers_link}. * Supports {docker_link}. * Supports link:https://git-scm.com[Git]. * Supports link:https://github.com[GitHub]. * Supports link:https://alchemists.io/projects/git-lint[Git Lint]. * Supports link:https://alchemists.io/projects/irb-kit[IRB Kit]. * Supports link:https://github.com/ruby/rake[Rake]. * Supports link:https://github.com/troessner/reek[Reek]. * Supports link:https://alchemists.io/projects/refinements[Refinements]. * Supports link:https://rspec.info[RSpec]. * Supports link:https://github.com/ruby/repl_type_completor[ReplTypeCompletor]. * Supports setup script for project setup. * Supports link:https://github.com/simplecov-ruby/simplecov[SimpleCov]. * Supports link:https://github.com/fxn/zeitwerk[Zeitwerk]. * Supports common settings and a structured layout for building projects. * Provides common documentation: ** README ** LICENSE ** VERSIONS ** Security ** Code of Conduct ** Contributions ** Developer Certificate of Origin ** Communities == Requirements . A UNIX-based system. . link:https://www.ruby-lang.org[Ruby]. == Setup To install _with_ security, run: [source,bash] ---- # 💡 Skip this line if you already have the public certificate installed. gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem) gem install rubysmith --trust-policy HighSecurity ---- To install _without_ security, run: [source,bash] ---- gem install rubysmith ---- == Usage === Command Line Interface (CLI) From the command line, type: `rubysmith --help` image:https://alchemists.io/images/projects/rubysmith/screenshots/usage.png[Usage,width=554,height=301,role=focal_point] ==== Build The core functionality of this gem centers around the `--build` command and associated options (flags). The build options allow you to further customize the kind of project you want to build. Most build options are enabled by default. Example: [source,bash] ---- rubysmith build --name demo ---- Running the above will generate a new `demo` Ruby project. Should you wish to disable specific options, you can use `--no-*` prefixes. Example: [source,bash] ---- rubysmith build --name demo --no-debug --no-reek ---- With the above example, both Debug and Reek support would have been disabled when building the `demo` project. Taking this a step further, you can also use the `--min` option to generate a project with bare minimum of options. Example: [source,bash] ---- rubysmith build --name demo --min ---- The above is essentially the same as building with _all_ options disabled. This is handy in situations where you need to quickly script something up for sharing with others yet still want to avoid using a {bundler_inline_link} script so gem dependencies are not installed each time the code is run. As shown earlier, you can combine options but be aware that order matters. Take the following, for example, where both minimum and maximum options are used in conjunction with other options: [source,bash] ---- rubysmith build --name demo --min --zeitwerk rubysmith build --name demo --max --no-debug ---- With the above examples, the first line will _disable_ all options except Zeitwerk while the second line will _enable_ all options except Debug. This can be a handy way to build a new project with all options either disabled or enabled with only a few select options modified. To have specific options enabled/disabled _every time_ you build a new Ruby project, you can edit your global configuration for making these settings permanent (see below for details). There is a lot of flexibility when building a new project through the various build options. I'll walk you through each so you can better understand why you'd want to enable or disable any one of them. ===== Amazing Print The `--amazing_print` option allows you to build your project with the link:https://github.com/amazing-print/amazing_print[Amazing Print] gem for debugging purposes and is a handy debugging tool when inspecting your Ruby objects and printing details in a quick to read format. ===== Bootsnap The `--bootsnap` option allows you to build your project with the link:https://github.com/Shopify/bootsnap[Bootsnap] gem for improved performance. This is best used for pure, non-gem, Ruby projects and/or web applications in general. ===== Caliber The `--caliber` option allows you to build your project with the link:https://alchemists.io/projects/caliber[Caliber] gem so you have an immediate working -- and high quality -- link:https://docs.rubocop.org/rubocop[RuboCop] configuration. Read the Caliber documentation for further customization. ===== Circle CI The `--circle_ci` option allows you to build your project with link:https://circleci.com[Circle CI] configured so you can get your project building as quickly as possible. ===== Citation The `--citation` option allows you to add a link:https://citation-file-format.github.io[citation] file to your project so you can help the research community cite your work in their studies if your project is used. ===== Community The `--community` option allows you to link to your open source community, organization, or group chat to help with community engagement of your work. ===== Code of Conduct The `--conduct` option allows you to link to your link:https://www.contributor-covenant.org[Code of Conduct] to encourage good community participation. Regardless of whether you have a community or not, the code of conduct is good to encourage in general. ===== Console The `--console` option allows you to add a `console` script for local development. So instead of typing `irb`, you can type `bin/console` and get an IRB session with all of your project's code loaded. ===== Contributions The `--contributions` option allows you to link to contributing documentation so people know to contribute back to your work. ===== Developer Certificate of Origin The `--dcoo` option allows to you add link:https://developercertificate.org[Developer Certificate of Origin] documentation so all contributors are aware of how their contributions are applied in terms of ownership, copyright, and licensing. ℹ️ This is disabled by default but will be enabled by default in the next major version. ===== Debug The `--debug` option allows you add the link:https://github.com/ruby/debug[Debug] gem to your project for debugging your code by setting breakpoints, remotely connecting to running code, and much more. ===== Docker The `--docker` option allows you add {docker_link} to your project so you can build and deploy to production. ===== Development Containers The `--devcontainer` option allows you add {development_containers_link} support to your project so you can develop locally by running your project within a {docker_link} container. ===== Funding The `--funding` option allows you add a link:https://github.com[GitHub] funding configuration to your project so you can attract link:https://docs.github.com/en/sponsors[sponsors]. This option doesn't require use of the `--git_hub` option but is encouraged. ===== Git The `--git` option allows you add link:https://git-scm.com[Git] repository support. Includes link:https://alchemists.io/screencasts/git_safe[Git Safe] functionality so you don't have to prefix commands with the `bin/` path prefix. Instead, you can call the command directly (assuming you have configured your link:https://alchemists.io/projects/dotfiles[Dotfiles] accordingly). ===== GitHub The `--git_hub` option allows you add link:https://github.com[GitHub] templates to your project for issues and pull requests. ===== GitHub CI The `--git_hub_ci` option allows you to build your project with link:https://docs.github.com/en/actions[GitHub Actions] configured so you can get your project building as quickly as possible. ===== Git Lint The `--git-lint` option allows you to add the link:https://alchemists.io/projects/git-lint[Git Lint] gem to your project to ensure you are crafting your Git commits in a consistent and readable manner. ===== Guard ⚠️ _This is deprecated and will be removed in the next major version._ The `--guard` option allows you add the link:https://github.com/guard/guard[Guard] gem to your project for rapid red, green, refactor development cycles. ===== IRB Kit The `--irb-kit` option allows you add the link:https://alchemists.io/projects/irb-kit[IRB Kit] gem to your project for additional extensions you can use within IRB to improve your workflow. ===== License The `--license` option ensures you build your project with a license. ===== Maximum The `--max` option allows you to build your project with _all_ options _enabled_. This is a quick way to build a new project with all options enabled without having to pick and choose. ===== Minimum The `--min` option allows you to build your project with _all_ options _disabled_. This is a quick way to build a new project with the bare minimum of support which is a one step above reaching for a {bundler_inline_link} script. ===== Rake The `--rake` option allows you to add the link:https://github.com/ruby/rake[Rake] gem for quickly crafting build scripts. ===== Readme The `--readme` option allows you to add README documentation to your project. ===== Reek The `--reek` option allows you add the link:https://github.com/troessner/reek[Reek] gem to your project for code smell and code quality support. ===== Refinements The `--refinements` option allows you to add the link:https://alchemists.io/projects/refinements[Refinements] gem to your project which enhances Ruby core objects without monkey patching your code. ===== RSpec The `--rspec` option allows you add the link:https://rspec.info[RSpec] gem to your project for defining your project specifications and have a framework for testing your code. ===== Repl Type Completor (RTC) The `--rtc` option allows you add the link:https://github.com/ruby/repl_type_completor[Repl Type Completor] gem to your project for improved type completion when using link:https://github.com/ruby/irb[IRB]. ===== Setup The `--setup` option allows you to configure you project with automated setup instructions so anyone new to your project can quickly get started by running the `bin/setup` script. ===== SimpleCov The `--simple_cov` option allows you add the link:https://github.com/simplecov-ruby/simplecov[SimpleCov] gem to your project to provide full analysis of what your quality of code is for the project. ===== Versions The `--versions` option allows you add a `VERSIONS` file to your project to provide details about all published versions of your project. ===== Zeitwerk The `--zeitwerk` option allows you add the link:https://github.com/fxn/zeitwerk[Zeitwerk] gem to your project so you can reduce the maintenance burden of managing requirements when adding new objects to your project. This includes having access to your project's Zeitwerk loader for inspection and debugging purposes. This means if you built a `Demo` project, you'd immediately have access to your project's loader via `Demo.loader` when using the project console (i.e. `bin/console`, assuming you built your project with the `--console` flag enabled which is default behavior). === Configuration This gem can be configured via a global configuration: .... $HOME/.config/rubysmith/configuration.yml .... It can also be configured via link:https://alchemists.io/projects/xdg[XDG] environment variables. The default configuration is as follows: [source,yaml] ---- author: handle: undefined uri: "%s/team/%s" build: amazing_print: true bootsnap: false caliber: true circle_ci: false citation: true cli: false community: false conduct: true console: true contributions: true dcoo: false debug: true devcontainer: false docker: false funding: false git: true git_hub: false git_hub_ci: false git_lint: true guard: false irb_kit: true license: true maximum: false minimum: false rake: true readme: true reek: true refinements: true rspec: true rtc: true security: true setup: true simple_cov: true versions: true zeitwerk: true citation: message: Please use the following metadata when citing this project in your work. documentation: format: "adoc" license: label: Hippocratic name: hippocratic version: "2.1" organization: uri: https://undefined.io project: uri: community: "%s/community" conduct: "%s/policies/code_of_conduct" contributions: "%s/policies/contributions" dcoo: "%s/policies/developer_certificate_of_origin" download: "https://rubygems.org/gems/%s" funding: "%s/sponsors/%s" home: "%s/projects/%s" issues: "%s/%s/%s/issues" license: "%s/policies/license" security: "%s/policies/security" source: "%s/%s/%s" versions: "%s/projects/%s/versions" version: 0.0.0 repository: handle: undefined uri: https://github.com ---- By customizing your configuration, you can change Rubysmith's default behavior when building projects. This is a great way to define your own specialized settings other than what is provide for you by default. This is also a handy way to provide additional information needed for some of the build options. You'll also notice some of the values use {string_formats_link} which means you can use any fully qualified key as a string specifier for supported keys like those found in the `author` and `project` sections. The next sections will walk you through each configuration so you can learn more. ==== Author Author information is used when generating project documentation and is recommended you fill this information in before building a project. Example: [source,yaml] ---- author: email: jsmith@example.com family_name: Smith given_name: Jill ---- If your global link:https://git-scm.com[Git] configuration is properly configured, your given name; family name; and email will be used by default. Should you not want to defer to Git, you can supply custom values as desired. The URI is the only value that can't be automatically computed for you. ==== Build All build options only accept booleans values and can be customized as desired. When changing your build options, they will dynamically render when displaying usage (i.e. `rubysmith --help`). All of these options have been explained in greater detail in the _Usage_ section. ℹ️ The `cli` option is provided to support {gemsmith_link} but is not, currently, used by this project. ==== Citations This section allows you to configure your link:https://orcid.org[ORCID] link:https://citation-file-format.github.io[citation] information used by the research community. You should definitely fill this in. Your author information, detailed above, will also be used when building this file. ==== Documentation Use this section to define the kind of documentation you want generated for your project. The following options are available: * `adoc` - Uses link:https://asciidoctor.org[ASCII Doc] format. * `md` - Uses link:https://asciidoctor.org[Markdown] format. ==== License Use this section to define the license you want to use for your project. When picking a license, you can supply the appropriate `label` and `version` in addition to the `name`. The `name` is the only value you _can't_ customize. The following details all supported licenses. ===== Apache To use the link:https://www.apache.org/licenses/LICENSE-2.0[Apache] license, apply this configuration: [source,yaml] ---- license: label: "Apache" name: "apache" version: "2.0" ---- ===== Fair Source To use the link:https://fsl.software[Fair Source] license, apply this configuration: [source,yaml] ---- license: label: "Fair Source" name: "fair" version: "FSL-1.1-Apache-2.0" ---- ===== Hippocratic To use the link:https://firstdonoharm.dev[Hippocratic] license, apply this configuration: [source,yaml] ---- license: label: "Hippocratic" name: "hippocratic" version: "2.1" ---- ℹ️ This is the default license unless you customize. ===== MIT To use the link:https://mit-license.org[MIT] license, apply this configuration: [source,yaml] ---- license: label: "MIT" name: "mit" version: "" ---- ==== Organization Use this section to define organization specific information. This is useful for information that isn't project specific but related to all projects within your organization. You'll want -- highly recommended -- to supply configuration details. For example, here's what a fictional organization might look like: [source,yaml] ---- organization: label: ACME uri: https://acme.io ---- ==== Project There are two sub-categories within this section: URIs and version. The URIs allow you to link to specific documentation related to your project. You'll want to customize these URIs since they are used for documentation, citations, and general project information. Some of the URIs are also used by the {gemsmith_link} gem. One powerful feature of this configuration is that you can use `%s` as a placeholder _anywhere_ in your URIs and Rubysmith will ensure your place holder is replaced with your project name when generating a new project. Example: .... # Configuration https://www.example.com/%s # Command rubysmith build --name demo # Actual (computed result) https://www.example.com/demo .... As for the `version` key, this defines the default version of newly created projects. `0.0.0` is the default but you can use a higher version number like `0.1.0` or even `1.0.0` if you are super confident in your work. That said, a lower the number is recommended when building your initial project which is why `0.0.0` is the default. ==== Repository Your repisotry handle is the handle you setup when creating your account (i.e. `+https://github.com/+`). This information is used for template, funding, and/or URI construction purposes. == Development To contribute, run: [source,bash] ---- git clone https://github.com/bkuhlmann/rubysmith cd rubysmith bin/setup ---- You can also use the IRB console for direct access to all objects: [source,bash] ---- bin/console ---- == Tests To test, run: [source,bash] ---- bin/rake ---- == link:https://alchemists.io/policies/license[License] == link:https://alchemists.io/policies/security[Security] == link:https://alchemists.io/policies/code_of_conduct[Code of Conduct] == link:https://alchemists.io/policies/contributions[Contributions] == link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin] == link:https://alchemists.io/projects/rubysmith/versions[Versions] == link:https://alchemists.io/community[Community] == Credits * Built with {gemsmith_link}. * Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].