Update manpage with information about alternative compilers by afnanenayet · Pull Request #4398 · Homebrew/brew

afnanenayet · 2018-06-30T20:05:28Z

This change references #4387. While I understand alternative compilers aren't officially supported, it is worth documenting Homebrew's behavior with the options that do allow users to compile with something besides Apple's bundled clang.

added a detail to the --cc param, stating how to use the Homebrew provided clang, also noting that issues should not be filed if this flag is used
removed trailing whitespace in the manpage's markdown source.

Note: I did not write any additional tests, because I did not change any functionality.

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?

* Update the manpage source file with additional information * document the `HOMEBREW_CC` variable with usage information * update usage information for `--cc`, specifying how to use llvm's clang

afnanenayet · 2018-06-30T23:31:07Z

I'm not sure what the proper way is to go about updating the documentation, it says that travis failed because the man pages changed.

jonchang · 2018-07-01T00:34:00Z

You'll need to run brew man to update the man pages and commit it with your pull request.

afnanenayet · 2018-07-01T21:30:26Z

Ah gotcha, thank you!

…r-docs

Use brew man to generate manpages, and then copy them to the repo.

jonchang · 2018-07-01T21:54:39Z

@afnanenayet my apologies for not being clearer. The manpages are automatically generated from documentation embedded in the Homebrew source files. So you need to update the documentation comments in the relevant files, and then run brew man to regenerate the manpages and commit it in the same pull request. This process could probably be better documented.

For the changes that you want, you'll need to update cmd/install.rb and manpages/brew.1.md.erb.

afnanenayet · 2018-07-01T22:02:56Z

Haha yeah I was very confused. Thanks for the pointer, maybe we should add this to the documentation as well.

Properly update man pages using the local brew executable (from the repo), and copy the man pages to the repo.

afnanenayet · 2018-07-02T00:10:05Z

@jonchang is there anything we can do about the code coverage?

Edit: JK, I thought that the codecov regression was blocking the merge

MikeMcQuaid · 2018-07-05T08:11:40Z

 #:    <compiler> should be the name of the compiler's executable, for instance
 #:    `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a Homebrew-provided GCC
-#:    4.9.
+#:    4.9. In order to use LLVM's clang, use `llvm_clang`. To specify the


Might be good to reference current versions e.g. gcc, gcc-6 or gcc-4.9? Could you also add Please do not file issues if you encounter errors when using this flag.

Yes for sure, I used those examples because that's what was documented previously, and I wasn't sure if I should change them

MikeMcQuaid · 2018-07-05T08:11:55Z


    *Default:* `~/Library/Caches/Homebrew`.

+  * `HOMEBREW_CC`:


I'd probably rather we left this undocumented as it's very likely to break things if you set it in your environment.

MikeMcQuaid · 2018-07-05T08:12:18Z

 * Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing
-C++11 support on earlier versions.
+  C++11 support on earlier versions.
 * Homebrew provides older GCC formulae, e.g. `gcc@4.8` and `gcc@6`.


gcc@4.9 and gcc@6?

MikeMcQuaid · 2018-07-05T08:12:41Z

@jonchang is there anything we can do about the code coverage?

Edit: JK, I thought that the codecov regression was blocking the merge

Yep, can just ignore code coverage on this PR 👍

…r-docs

* update references in `--cc` flag, using modern gcc examples * note that issues should not be filed if `--cc` flag is used * remove reference to `HOMEBREW_CC` as it should not be exposed to users * generate manpages using `brew man` with these changes

This fixes the rubocop offences, which was blocking Travis

Generate new man pages so that the docs and manpages match up

MikeMcQuaid

Couple more tiny tweaks then good to 🚢! Thanks again.

MikeMcQuaid · 2018-07-06T19:45:24Z

+#:    Homebrew-provided GCC 4.9. In order to use LLVM's clang, use
+#:    `llvm_clang`. To specify the Apple-provided clang, use `clang`. This
+#:    parameter will only accept compilers that are provided by Homebrew or
+#:    bundled with MacOS. Please do not file issues if you encounter errors


I've been spelling it wrong all this time...O.o

* change `MacOS` -> `macOS` * regenerate manpages

…r-docs

MikeMcQuaid · 2018-07-07T12:45:18Z

Thanks so much for your first contribution! Without people like you submitting PRs we couldn't run this project. You rock, @afnanenayet!

afnanenayet · 2018-07-07T13:53:23Z

@MikeMcQuaid @jonchang I really appreciate how you guys helped me out despite me not knowing anything about how homebrew is structured and literally taking 10 commits to update some doc -- really appreciate the encouragement :)

Update manpage with info about compilers

a68f1ff

* Update the manpage source file with additional information * document the `HOMEBREW_CC` variable with usage information * update usage information for `--cc`, specifying how to use llvm's clang

afnanenayet added 2 commits July 1, 2018 17:32

Merge branch 'master' of github.com:Homebrew/brew into update-compile…

51bf657

…r-docs

Update manpages using the brew man command

01a3422

Use brew man to generate manpages, and then copy them to the repo.

Update manpages using man brew

fa41a66

Properly update man pages using the local brew executable (from the repo), and copy the man pages to the repo.

MikeMcQuaid reviewed Jul 5, 2018

View reviewed changes

afnanenayet added 4 commits July 5, 2018 17:23

Merge branch 'master' of github.com:Homebrew/brew into update-compile…

fd84bcb

…r-docs

Strip trailing whitespaces

9579fad

This fixes the rubocop offences, which was blocking Travis

Update man pages to reflect prior change

75d3ca8

Generate new man pages so that the docs and manpages match up

MikeMcQuaid reviewed Jul 6, 2018

View reviewed changes

afnanenayet added 2 commits July 6, 2018 23:06

Fix typo

133c3a3

* change `MacOS` -> `macOS` * regenerate manpages

Merge branch 'master' of github.com:Homebrew/brew into update-compile…

84b03c5

…r-docs

MikeMcQuaid approved these changes Jul 7, 2018

View reviewed changes

MikeMcQuaid merged commit b350fe0 into Homebrew:master Jul 7, 2018

afnanenayet deleted the update-compiler-docs branch July 7, 2018 13:58

lock bot added the outdated PR was locked due to age label Aug 6, 2018

lock bot locked as resolved and limited conversation to collaborators Aug 6, 2018

Uh oh!

Conversation

afnanenayet commented Jun 30, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

afnanenayet commented Jun 30, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonchang commented Jul 1, 2018

Uh oh!

afnanenayet commented Jul 1, 2018

Uh oh!

jonchang commented Jul 1, 2018

Uh oh!

afnanenayet commented Jul 1, 2018

Uh oh!

afnanenayet commented Jul 2, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MikeMcQuaid Jul 5, 2018

Choose a reason for hiding this comment

Uh oh!

afnanenayet Jul 5, 2018

Choose a reason for hiding this comment

Uh oh!

MikeMcQuaid Jul 5, 2018

Choose a reason for hiding this comment

Uh oh!

MikeMcQuaid Jul 5, 2018

Choose a reason for hiding this comment

Uh oh!

MikeMcQuaid commented Jul 5, 2018

Uh oh!

MikeMcQuaid left a comment

Choose a reason for hiding this comment

Uh oh!

MikeMcQuaid Jul 6, 2018

Choose a reason for hiding this comment

Uh oh!

afnanenayet Jul 7, 2018

Choose a reason for hiding this comment

Uh oh!

MikeMcQuaid commented Jul 7, 2018

Uh oh!

afnanenayet commented Jul 7, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

afnanenayet commented Jun 30, 2018 •

edited

Loading

afnanenayet commented Jun 30, 2018 •

edited

Loading

afnanenayet commented Jul 2, 2018 •

edited

Loading