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