From 9f11ef9aa11da66166b2bc6309497ecc0928ae8a Mon Sep 17 00:00:00 2001 From: Phil Dibowitz Date: Mon, 1 Jan 2024 14:54:20 -0800 Subject: [PATCH] Add some specifics on gems (and maybe pips) In https://github.com/Homebrew/homebrew-core/pull/157910 we discussed some improvements to docs on setting up gems. THis is an attempt at some docs for that. If someone can help with pip docs for this I'll add it too. Signed-off-by: Phil Dibowitz --- docs/Formula-Cookbook.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index ad39e98597..6716e8afe0 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -60,6 +60,8 @@ Run `brew create` with a URL to the source tarball: brew create https://example.com/foo-0.1.tar.gz ``` +Passing in `--ruby` or `--python` will populate various defaults commonly useful for projects written in those languages. + This creates `$(brew --repository)/Library/Taps/homebrew/homebrew-core/Formula/f/foo.rb` and opens it in your `EDITOR`. If run without any options to customize the output for specific build systems (check `brew create --help` to see which are available) it'll look something like: ```ruby @@ -251,7 +253,36 @@ uses_from_macos "curl", since: :monterey Homebrew doesn’t package already-packaged language-specific libraries. These should be installed directly from `gem`/`cpan`/`pip` etc. -If you're installing an application then use [`resource`](https://rubydoc.brew.sh/Formula#resource-class_method)s for all language-specific dependencies: +### Ruby Gem Dependencies + +The preferred mechanism for installing gem dependencies is to use `bundler` with the upstream's `Gemfile.lock`. This requires the upstream checks in their `Gemfile.lock`, so if they don't, it's a good idea to file an issue and ask them to do so. Assuming they have one, this is as simple as: + +```ruby +ENV["GEM_HOME"] = libexec +system "bundle", "install", "--without", "development" +``` + +From there, you can build and install the project itself: + +```ruby +system "gem", "build", ".gemspec" +system "gem", "install", "--ignore-dependencies", "-#{version}.gem" +``` + +And install any bins, and munge their shebang lines, with: + +```ruby +bin.install libexec/"bin/" +bin.env_script_all_files(libexec/"bin", GEM_HOME: ENV["GEM_HOME"]) +``` + +### Python dependencies + +For python we [`resource`](https://rubydoc.brew.sh/Formula#resource-class_method)s for dependencies and there's automation to generate these for you. Running `brew update-python-resources ` will automatically add the necessary [`resource`](https://rubydoc.brew.sh/Formula#resource-class_method) stanzas for the dependencies of your Python application to the formula. Note that `brew update-python-resources` is run automatically by `brew create` if you pass the `--python` switch. If `brew update-python-resources` is unable to determine the correct `resource` stanzas, [homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) is a good third-party alternative that may help. + +### All other cases + +If all else fails, you'll want to use [`resource`](https://rubydoc.brew.sh/Formula#resource-class_method)s for all other language-specific dependencies. This requires you to specify both a specific URL for a version and the sha256 checksum for security. Here's an example: ```ruby class Foo < Formula @@ -268,8 +299,6 @@ end [`jrnl`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/j/jrnl.rb) is an example of a formula that does this well. The end result means the user doesn't have to use `pip` or Python and can just run `jrnl`. -For Python formulae, running `brew update-python-resources ` will automatically add the necessary [`resource`](https://rubydoc.brew.sh/Formula#resource-class_method) stanzas for the dependencies of your Python application to the formula. Note that `brew update-python-resources` is run automatically by `brew create` if you pass the `--python` switch. If `brew update-python-resources` is unable to determine the correct `resource` stanzas, [homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) is a good third-party alternative that may help. - ### Install the formula ```sh