[docs] added installation guide with Homebrew

[StrikerRUS]

Closed #2408.

[jameslamb]

Nice! Thanks again for adding this support @ankane

[ankane]

Thank you both.

@StrikerRUS I feel like it probably shouldn't be nested under Clang, since it's already pre-compiled. I'd probably do something like:

---

On macOS, LightGBM can be installed with Homebrew or built using Apple Clang or gcc.

Homebrew

...

Apple Clang

...

gcc

...

[StrikerRUS]

@ankane

I feel like it probably shouldn't be nested under Clang

Oh, it was my headache for about an hour when I prepared this PR! Yes, with Homebrew users mostly install pre-compiled bottles. But can these bottles be used with gcc?

[ankane]

@StrikerRUS As far as I know, the bottles don't require any compiler. Overall, I'm thinking it'd be good to separate out the install and build from source instructions. Currently, it looks like the Homebrew instructions are part of the build from source docs (imho).

[StrikerRUS]

@ankane

As far as I know, the bottles don't require any compiler.

According to the docs, bottle can be treated as compiled binary file. According to this part of formula, bottles are built against AppleClang with libomp. I'm not sure that library linked to libomp can run successfully on system with gomp installed. As a side note it's worth to say that there is a lot of headache with supporting projects with OpenMP, e.g.,

LightGBM/.ci/test.sh

Lines 71 to 74 in 0237492

	if [[ $OS_NAME == "macos" ]] && [[ $COMPILER == "clang" ]]; then
	# fix "OMP: Error #15: Initializing libiomp5.dylib, but found libomp.dylib already initialized." (OpenMP library conflict due to conda's MKL)
	for LIBOMP_ALIAS in libgomp.dylib libiomp5.dylib libomp.dylib; do sudo ln -sf "$(brew --cellar libomp)"/*/lib/libomp.dylib $CONDA_PREFIX/lib/$LIBOMP_ALIAS || exit -1; done
	fi

UPD: Now I'm sure:
https://github.com/Homebrew/homebrew-core/blob/823eecea753a7bd7932b0a3ec81ed27c392c5cc9/Formula/libomp.rb#L18-L19

So, I think we should inform users about that downloaded bottles will run under AppleClang. For someone it may be important.

Overall, I'm thinking it'd be good to separate out the install and build from source instructions. Currently, it looks like the Homebrew instructions are part of the build from source docs (imho).

Agree! Seems that using your descriptive sentence with the current structure will help. I'll push changes in a little while.

[StrikerRUS]

@ankane It should be more clear now that Homebrew allows installation in contrast to building from sources.

[ankane]

Thanks @StrikerRUS. I still think it'll be easier for users to understand if it's not under the Apple Clang section (most Homebrew users shouldn't need to know anything about how it was compiled), but understand if you don't agree.