New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs/Linuxbrew.md #5483

Merged
merged 1 commit into from Jan 7, 2019

Conversation

Projects
None yet
5 participants
@sjackman
Copy link
Contributor

sjackman commented Jan 4, 2019

  • Have you followed the guidelines in our Contributing document?
  • Have you checked to ensure there aren't other open Pull Requests for the same change?
  • Have you added an explanation of what your changes do and why you'd like us to include them?
  • Have you written new tests for your changes? Here's an example.
  • Have you successfully run brew style with your changes locally?
  • Have you successfully run brew tests with your changes locally?

@sjackman sjackman self-assigned this Jan 4, 2019

@sjackman sjackman requested review from iMichka , jonchang and MikeMcQuaid Jan 4, 2019


# Linuxbrew

The Homebrew package manager may be used on Linux and Windows 10+, using [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/about), as well as macOS. Homebrew is referred to as Linuxbrew when running on Linux or Windows. It can be installed in your home directory and does not require root access. Recent versions of *glibc* and *gcc* may be installed in your home directory on an older distribution of Linux. A Linuxbrew installation does not use any libraries provided by your host system, except *glibc* and *gcc* if they are sufficiently current.

This comment has been minimized.

@jonchang

jonchang Jan 4, 2019

Member

A Linuxbrew installation does not use any libraries provided by your host system, except *glibc* and *gcc* if they are sufficiently current. Otherwise, versions of *glibc* and *gcc* may be installed in your home directory on an older distribution of Linux.

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 4, 2019

Contributor

First sentence:

Besides macOS, Homebrew also supports Linux and Windows 10+ (via its Windows Subsystem for Linux (WSL)).

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

I'm inclined to remove the mention of macOS, as its stating the obvious to say that Homebrew runs on macOS.

This comment has been minimized.

@jonchang

jonchang Jan 4, 2019

Member

Maybe: "The Homebrew package manager may also be used on Linux and Windows 10+, using Windows Subsystem for Linux (WSL)."

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

I'm inclined to remove the mention of macOS, as its stating the obvious to say that Homebrew runs on macOS.

Agreed.

does not require root access

does not use the root user

may be installed in your home directory

may be installed in your Homebrew prefix (or some similar wording that still works if Linuxbrew is installed outside the home directory)

if they are sufficiently current.

if they are new enough

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

does not require root access.

does not use the root user.

went with does not require sudo.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 6, 2019

Member

@sjackman I'm being pedantic but I think it's worth noting when things like sudo are mentioned that after installation it doesn't use it (ever) rather than doesn't require it (which sounds like it will if it can)

This comment has been minimized.

@sjackman

sjackman Jan 6, 2019

Contributor

Went with…

It can be installed in your home directory, in which case it does not use sudo.

The installation script installs Linuxbrew to /home/linuxbrew/.linuxbrew using sudo if possible and in your home directory at ~/.linuxbrew otherwise. Linuxbrew does not use sudo after installation.


# Linuxbrew

The Homebrew package manager may be used on Linux and Windows 10+, using [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/about), as well as macOS. Homebrew is referred to as Linuxbrew when running on Linux or Windows. It can be installed in your home directory and does not require root access. Recent versions of *glibc* and *gcc* may be installed in your home directory on an older distribution of Linux. A Linuxbrew installation does not use any libraries provided by your host system, except *glibc* and *gcc* if they are sufficiently current.

This comment has been minimized.

@iMichka

iMichka Jan 4, 2019

Contributor

as well as macOS. -> as well as on macOS.?
Or maybe just remove that bit?

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

It does seem like stating the obvious.

@@ -7,6 +7,7 @@
- [Frequently Asked Questions](FAQ.md)
- [Common Issues](Common-Issues.md)
- [`brew` Shell Completion](Shell-Completion.md)
- [Linuxbrew: Homebrew on Linux and Windows](Linuxbrew.md)

This comment has been minimized.

@iMichka

iMichka Jan 4, 2019

Contributor

There is an Installation page above for mac, should we add a comment there for a Linux installation? Or should we try to regroup both installation procedures in one page?

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

Eventually I'd like the same installation procedure (one-line shell snippet) to be used for both macOS and Linux. In the mean time, https://linuxbrew.sh will be the go-to resource for installation instructions.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

"and Windows 10".

+ Can install software to your home directory and so does not require sudo
+ Install software not packaged by your host distribution
+ Install up-to-date versions of software when your host distribution is old
+ Use the same package manager to manage your macOS, Linux, and Windows systems

This comment has been minimized.

@iMichka

iMichka Jan 4, 2019

Contributor

Is that text not already somewhere else in the mac doc?

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

It may be, but I don't think it hurts to reiterate the fact here as a feature of Linuxbrew.

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 4, 2019

Contributor

I concur with @iMichka: this section is redundant IMHO

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

These features are particularly relevant to Linux users of Homebrew.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

Feels a bit weird to list features after install instructions

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

Move Features above Install.


- [@Linuxbrew on Twitter](https://twitter.com/Linuxbrew)
- [Linuxbrew/core on GitHub](https://github.com/Linuxbrew/homebrew-core)
- [Linuxbrew Discourse](https://discourse.brew.sh/c/linuxbrew)

This comment has been minimized.

@iMichka

iMichka Jan 4, 2019

Contributor

This should go on the main homebrew readme page.

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

Agreed, but it doesn't hurt to reiterate it here.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

"Linuxbrew category of Homebrew's Discourse"


[<img alt="CircleCI logo" style="height:1in" src="https://assets.brandfolder.com/otz6k5-cj8pew-e4rk9u/original/circle-logo-horizontal-black.png">](https://circleci.com/)

[![Downloads by Bintray](https://bintray.com/docs/images/downloads_by_bintray_96.png)](https://bintray.com/linuxbrew)

This comment has been minimized.

@iMichka

iMichka Jan 4, 2019

Contributor

And this part can go on the main readme page too.

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

We both use Bintray, and that's acknowledged already. Homebrew doesn't use CircleCI though, so here is a better spot for it.


[Features](#features), [dependencies](#dependencies) and [installation instructions](#install) are described below. Terminology (e.g. the difference between a Cellar, Tap, Cask and so forth) is [explained in the documentation](https://docs.brew.sh/Formula-Cookbook#homebrew-terminology).

# Install

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 4, 2019

Contributor

I suggest using ## Install: there should be only one header (# Linuxbrew) IMHO.

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

In my opinion, <title> is for the title of the document, and <h1> (aka #) is for the first level of section headers.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

I agree with @maxim-belkin. This will look weird on docs.brew.sh otherwise.

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

Alrighty. I'll give in… this time. =p


# Install

The installation script installs Linuxbrew to `/home/linuxbrew/.linuxbrew` if possible and in your home directory at `~/.linuxbrew` otherwise. Using `/home/linuxbrew/.linuxbrew` allows the use of more binary packages, called bottles, than installing in your personal home directory.

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 4, 2019

Contributor

, called bottles, ~> ("bottles") or ,aka "bottles", or ("bottles" in Homebrew terminology)
than ~> rather than

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

I generally prefer parenthetical commas over parentheses in my writing. I don't feel strongly about this one. Perhaps

… binary packages (bottles) than installing …

This comment has been minimized.

@jonchang

jonchang Jan 4, 2019

Member
$ rg 'binary.*bottle|bottle.*binary'
diagnostic.rb:          You can install Homebrew anywhere you want but some bottles (binary packages)
brew.sh:you being able to use all the binary packages (bottles) Homebrew provides. We
build_options.rb:  # True if a {Formula} is being built as a bottle (i.e. binary package).
formula.rb:  # When installing a bottle (binary package) from a local path this will be
cmd/vendor-install.sh:both Bintray (used for Homebrew bottles/binary packages) and GitHub
dev-cmd/bottle.rb:#:    Generate a bottle (binary package) from a formula that was installed with
dev-cmd/bottle.rb:        Generate a bottle (binary package) from a formula that was installed with
extend/os/linux/diagnostic.rb:          You will be unable to use binary packages (bottles).

This comment has been minimized.

@jonchang

jonchang Jan 4, 2019

Member

Looks like parenthetical style for defining bottles is more common in the Homebrew codebase.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

if possible

when would it not be possible?

agreed with matching existing style

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

The installation script installs Linuxbrew to /home/linuxbrew/.linuxbrew if possible

when would it not be possible?

When the user does not have sudo permissions on their system.


```sh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/Linuxbrew/install/master/install.sh)"
```

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 4, 2019

Contributor

I suggest moving this snippet up to right below the # Install and then going into details about it...

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

Agreed.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/Linuxbrew/install/master/install.sh)"
```

Follow the *Next steps* instructions to add Linuxbrew to your `PATH` and to your bash shell profile script, either `~/.profile` on Debian/Ubuntu or `~/.bash_profile` on CentOS/Fedora/RedHat.

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 4, 2019

Contributor

why *Next steps*?

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

That's the text output by the installer script for both Homebrew and Linuxbrew.

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 6, 2019

Contributor

sudo -> sudo ?


```sh
test -d ~/.linuxbrew && eval $(~/.linuxbrew/bin/brew shellenv)
test -d /home/linuxbrew/.linuxbrew && eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv)

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 4, 2019

Contributor

it just occurred to me... -d tests if directory exists. We need to test -d, -w, and -x

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

If the directory exists, I prefer the user get an error message if it's not also -w or -x, as with the current code.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

What if neither exist?

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

These commands are meant to be run after a successful run of sh -c "$(curl -fsSL https://raw.githubusercontent.com/Linuxbrew/install/master/install.sh)", after which one of these two directories will exist.


# Bottles

Bottles are Linuxbrew's precompiled binary packages. Linuxbrew bottles work on any Linux system. If you're using an older distribution of Linux, installing your first package will also install a recent version of `glibc` and `gcc`.

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 4, 2019

Contributor

"Bottles"

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

I prefer not to add scare quotes around each use of the word bottles.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

This seems to repeat stuff from above.

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

Deleted.


# Linuxbrew

The Homebrew package manager may be used on Linux and Windows 10+, using [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/about), as well as macOS. Homebrew is referred to as Linuxbrew when running on Linux or Windows. It can be installed in your home directory and does not require root access. Recent versions of *glibc* and *gcc* may be installed in your home directory on an older distribution of Linux. A Linuxbrew installation does not use any libraries provided by your host system, except *glibc* and *gcc* if they are sufficiently current.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

I'm inclined to remove the mention of macOS, as its stating the obvious to say that Homebrew runs on macOS.

Agreed.

does not require root access

does not use the root user

may be installed in your home directory

may be installed in your Homebrew prefix (or some similar wording that still works if Linuxbrew is installed outside the home directory)

if they are sufficiently current.

if they are new enough


The Homebrew package manager may be used on Linux and Windows 10+, using [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/about), as well as macOS. Homebrew is referred to as Linuxbrew when running on Linux or Windows. It can be installed in your home directory and does not require root access. Recent versions of *glibc* and *gcc* may be installed in your home directory on an older distribution of Linux. A Linuxbrew installation does not use any libraries provided by your host system, except *glibc* and *gcc* if they are sufficiently current.

[Features](#features), [dependencies](#dependencies) and [installation instructions](#install) are described below. Terminology (e.g. the difference between a Cellar, Tap, Cask and so forth) is [explained in the documentation](https://docs.brew.sh/Formula-Cookbook#homebrew-terminology).

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

Ideally use a Markdown file link here instead


[Features](#features), [dependencies](#dependencies) and [installation instructions](#install) are described below. Terminology (e.g. the difference between a Cellar, Tap, Cask and so forth) is [explained in the documentation](https://docs.brew.sh/Formula-Cookbook#homebrew-terminology).

# Install

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

I agree with @maxim-belkin. This will look weird on docs.brew.sh otherwise.


# Install

The installation script installs Linuxbrew to `/home/linuxbrew/.linuxbrew` if possible and in your home directory at `~/.linuxbrew` otherwise. Using `/home/linuxbrew/.linuxbrew` allows the use of more binary packages, called bottles, than installing in your personal home directory.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

if possible

when would it not be possible?

agreed with matching existing style


```sh
test -d ~/.linuxbrew && eval $(~/.linuxbrew/bin/brew shellenv)
test -d /home/linuxbrew/.linuxbrew && eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv)

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

What if neither exist?


## Raspberry Pi

Linuxbrew can run on Raspberry Pi (32-bit ARM), but no binary packages (bottles) are available. Support for Raspberry Pi is on a best-effort basis. Pull requests are welcome to improve the experience on Raspberry Pi.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

If a "best-effort basis" and no binary packages I think this should be stated by brew doctor and the pre-installation instructions (like on old versions of macOS)

This comment has been minimized.

@sjackman

sjackman Jan 4, 2019

Contributor

Okay. I'll address that in a separate PR.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 6, 2019

Member

Cool, thanks.


## 32-bit x86

Linuxbrew does not currently support 32-bit x86 platforms. It would be possible for Linuxbrew to work on 32-bit x86 platforms with some effort. Pull requests would be welcome if someone were to volunteer to maintain the 32-bit x86 support.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

Personally I'm not sure the "pull requests would be welcome" part; it'd better be to suggest starting a dedicated fork like Tigerbrew and it could be merged back if it's used.

This comment has been minimized.

@sjackman

sjackman Jan 6, 2019

Contributor

Went with…

Linuxbrew does not currently support 32-bit x86 platforms. It would be possible for Linuxbrew to work on 32-bit x86 platforms with some effort. An interested and dedicated person could maintain a fork of Homebrew to develop support for 32-bit x86.


# Bottles

Bottles are Linuxbrew's precompiled binary packages. Linuxbrew bottles work on any Linux system. If you're using an older distribution of Linux, installing your first package will also install a recent version of `glibc` and `gcc`.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

This seems to repeat stuff from above.


- [@Linuxbrew on Twitter](https://twitter.com/Linuxbrew)
- [Linuxbrew/core on GitHub](https://github.com/Linuxbrew/homebrew-core)
- [Linuxbrew Discourse](https://discourse.brew.sh/c/linuxbrew)

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

"Linuxbrew category of Homebrew's Discourse"

@@ -7,6 +7,7 @@
- [Frequently Asked Questions](FAQ.md)
- [Common Issues](Common-Issues.md)
- [`brew` Shell Completion](Shell-Completion.md)
- [Linuxbrew: Homebrew on Linux and Windows](Linuxbrew.md)

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Jan 4, 2019

Member

"and Windows 10".

@sjackman sjackman force-pushed the sjackman:docs-linuxbrew branch from ef805ef to 9b09cdf Jan 4, 2019

@sjackman

This comment has been minimized.

Copy link
Contributor

sjackman commented Jan 4, 2019

I believe I've addressed all your comments. Thanks for your feedback. Ready for re-review.

@sjackman sjackman force-pushed the sjackman:docs-linuxbrew branch from 9b09cdf to 98723c4 Jan 6, 2019

@MikeMcQuaid
Copy link
Member

MikeMcQuaid left a comment

Thanks @sjackman!


# Linuxbrew

The Homebrew package manager may be used on Linux and Windows 10, using [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/about). Homebrew is referred to as Linuxbrew when running on Linux or Windows. It can be installed in your home directory, in which case it does not use sudo. Linuxbrew does not use any libraries provided by your host system, except *glibc* and *gcc* if they are new enough. Linuxbrew can install its own current versions of *glibc* and *gcc* for older distribution of Linux.

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 6, 2019

Contributor

sudo -> sudo ?

This comment has been minimized.

@sjackman

sjackman Jan 6, 2019

Contributor

Went with sudo


- [@Linuxbrew on Twitter](https://twitter.com/Linuxbrew)
- [Linuxbrew/core on GitHub](https://github.com/Linuxbrew/homebrew-core)
- [Linuxbrew category of Homebrew's Discourse](https://discourse.brew.sh/c/linuxbrew)

This comment has been minimized.

@maxim-belkin

maxim-belkin Jan 6, 2019

Contributor

[Linuxbrew category](https://discourse.brew.sh/c/linuxbrew) of [Homebrew's Discourse](proper-link-here) ?

@sjackman sjackman force-pushed the sjackman:docs-linuxbrew branch from 98723c4 to 441d28d Jan 6, 2019

@sjackman sjackman force-pushed the sjackman:docs-linuxbrew branch from 441d28d to f25eff1 Jan 6, 2019

@sjackman sjackman merged commit 464b41e into Homebrew:master Jan 7, 2019

1 check passed

coverage/coveralls First build on docs-linuxbrew at 71.263%
Details

@sjackman sjackman deleted the sjackman:docs-linuxbrew branch Jan 7, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment