How to create a tap...?

[nicolasnoble]

Alright, I'm thoroughly confused about the documentation and the process. Note that I do not own a mac, and that this process is mainly to help some niche users. My testing and experimenting has been done through github actions so far.

I've created two formulae in my repository, here:

https://github.com/grumpycoders/pcsx-redux/tree/main/tools/macos-mips

If I do a brew install of the files locally, it works fine:

https://github.com/grumpycoders/pcsx-redux/blob/main/.github/workflows/toolchain.yml#L23-L26

But doing a brew install on the URL doesn't work, with the following error:

$ brew install https://github.com/grumpycoders/pcsx-redux/blob/main/tools/macos-mips/mipsel-none-elf-gcc.rb
  shell: /bin/bash -e {0}
'brew extract' or 'brew create' and 'brew tap-new' to create a formula file in a tap on GitHub instead.: Invalid usage: Non-checksummed download of mipsel-none-elf-gcc formula file from an arbitrary URL is unsupported!  (UsageError)

I tried following the documentation from https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap using a Linux command line and brew installed, but I'm not sure it's even the proper path to making this work.

Since I already have a git repository, I did brew tap-new --no-git foo/bar to see what would happen, but none of my local files got changed, or created, and it went and created files in $(LINUXBREW)/Homebrew/Library/Taps/foo/homebrew-bar/ that have no seemingly relevant files created in it that'd need to be committed to my repository to make the error go away.

At this point, I have no clue whatsoever what's involved in making this work properly for mac users.

[gromgit]

I tried following the documentation from https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap using a Linux command line and brew installed, but I'm not sure it's even the proper path to making this work.

It's the only official "path to making this work".

Have you read https://docs.brew.sh/Taps? It's the very first link after the title, and explains what a tap is, its naming conventions and assumptions, and other useful info.

If you want to see an actual tap in action, look no further than the Homebrew core tap: ls $(brew --repo homebrew/core)

[nicolasnoble]

I have, and none of the information there answers the "what am I missing here?" question.

[SMillerDev]

I've created two formulae in my repository, here:
https://github.com/grumpycoders/pcsx-redux/tree/main/tools/macos-mips

This is all that a tap is really. You already have one.

brew tap-new I believe is the command to do the same thing from the commandline.

[nicolasnoble]

It's simply not working. brew tap-new isn't mutating my existing repository, only creates a new one, and then it's not installing packages when trying to do brew install:

brew install https://github.com/grumpycoders/pcsx-redux/blob/main/tools/macos-mips/mipsel-none-elf-gcc.rb fails
brew install https://github.com/grumpycoders/pcsx-redux/blob/main/tools/macos-mips/mipsel-none-elf-gcc fails

and various other naming schemes I've tried that I forgot about. All fail with the same error that I've already pasted originally.

[nicolasnoble]

This is all that a tap is really. You already have one.

So apparently not. After more digging, it seems that this isn't the case, and I came here as confused as you were. But to actually be a tap, the files need to be either in the root folder, in the /Formula folder, or in the /HomebrewFormula folder.

[carlocab]

Put your formula *.rb files in a directory called Formula in a git repository of your choice. GitHub would be simplest, and so would naming the repository homebrew-*.

Supposing you’ve done this for formula foo.rb in GitHub repo bar/homebrew-qux, users can install your formula using

brew tap bar/qux
brew install foo

or with

brew install bar/qux/foo

[nicolasnoble]

I don't mind moving the files into a Formula directory, as long as it's a subdirectory, like tools/mips-macos/Formula. Would this work or does it have to be at the root? This confuses me:

Tap formulae follow the same format as the core’s ones, and can be added under either the Formula subdirectory, the HomebrewFormula subdirectory or the repository’s root. The first available directory is used, other locations will be ignored. We recommend use of subdirectories because it makes the repository organisation easier to grasp, and top-level files are not mixed with formulae.

[nicolasnoble]

Yeah, it's not working. I find the documentation would be clearer if it dropped the prefix "sub" in the words here. The rb files have to be either in root, or in the /Formula directory, or in the /HomebrewFormula directory, and that's it. Nothing else is allowed.

Oh well.

[carlocab]

A tap isn't meant to be the same repo as your source code anyway, so it seems like you're wanting this for a use-case that isn't supported.

[nicolasnoble]

A tap isn't meant to be the same repo as your source code anyway, so it seems like you're wanting this for a use-case that isn't supported.

I am coming to this conclusion too. The documentation isn't making this clear at all. This paragraph in particular makes it look like this would be much more flexible:

If it’s on GitHub, users can install any of your formulae with brew install user/repo/formula. Homebrew will automatically add your github.com/user/homebrew-repo tap before installing the formula. user/repo/formula points to the github.com/user/homebrew-repo/**/formula.rb file here.
If they want to get your tap without installing any formula at the same time, users can add it with the brew tap command.
If it’s on GitHub, they can use brew tap user/repo, where user is your GitHub username and homebrew-repo is your repository.
If it’s hosted outside of GitHub, they have to use brew tap user/repo , where user and repo will be used to refer to your tap and is your Git clone URL.

But it's not the case at all.

[SMillerDev]

I am coming to this conclusion too. The documentation isn't making this clear at all.

I don't think I've ever seen a case where the software distribution was part of the source code in ~5 years of being a homebrew contributor. I'm not sure our documentation needs to explicitly mention such an exceptional case. I'd happily review a pull request to improve it though.

[Rylan12]

I think the confusion stems from the fact that brew tap-new creates a new tap. brew tap installs an existing tap.

If you must have your formula files in the same repo (not recommended), you want to run brew tap grumpycoders/pcsx-redux https://github.com/grumpycoders/pcsx-redux.

Then, you can install the formula with brew install $(brew --repository grumpycoders/pcsx-redux)/tools/macos-mips/mipsel-none-elf-binutils.rb

However, as Adrian and Sean mentioned, this isn't the recommended/supported way to host a tap, so it's possible that you'll run into some issues. A better option is to have a separate repo called grumpycoders/homebrew-pcsx-redux. That will allow users to simply run brew install grumpycoders/pcsx-redux/mipsel-none-elf-binutils to install the formula.

More information about creating (which is when you use tap-new) and hosting a tap is in the documentation.

[nicolasnoble]

Thanks, this is the sort of information I was looking for. This is indeed too convoluted, and I was hoping for something more straightforward.

I'll just let users do local installations, since this is only to be used within the same codebase as the repository itself, and has little other benefit:

https://github.com/grumpycoders/pcsx-redux#macos

[carlocab]

What's stopping you from setting up a separate repo for your tap? That's what very many other taps do.