Update doc repo build method on macOS

[minsoochoo0122_proton.me]

Summary

Asciidoctor should be installed via gem, not via Homebrew. Asciidoctor-pdf and Asciidoctor-epub3 should be also installed. Links of packages installed by gem should be created in /usr/local/bin directory.

Test Plan

cd documentation
bmake run LOCALBASE=/usr/local

[jlduran_gmail.com]

documentation/content/en/books/fdp-primer/overview/_index.adoc

261–263

I believe each version of Homebrew may have a different path. How about discovering it first by issuing:

$ brew --prefix ruby
/opt/homebrew/opt/ruby

270

If ruby is installed by Homebrew, why use sudo here?

273

Why? Is PATH not OK? Are the gems not pristined?

[jlduran_gmail.com]

I took a closer look at this, and I think one solution could be just to patch the Makekile in the documentation directory.

The problem is that the rouge binaries (rougify), installed by gem are in a different path. This predicament is not present on FreeBSD/Linux because you are instructed to install everything with a package manager, which installs all the binaries in the same place.

I have deployed a simple GitHub repo illustrating this issue. It patches the Makefile. You can verify in the artifacts for each run that the documentation builds successfully (it uploads a documentation.zip file containing the public directory).

In the meantime, perhaps a quick solution would be to define:

ROUGIFY_CMD?= ${LOCALBASE}/bin/rougify

So it can be overridden:

$ bmake run ROUGIFY_CMD=${GEM_PATH}/rougify

My main issue with this patch are the symlinks.

[minsoochoo0122_proton.me]

documentation/content/en/books/fdp-primer/overview/_index.adoc

270

Here's an explanation on stackoverflow

273

Unlike Homebrew, jem does not create symlinks in /usr/local/bin

[minsoochoo0122_proton.me]

In D37143#843876, @jlduran_gmail.com wrote:

I took a closer look at this, and I think one solution could be just to patch the Makekile in the documentation directory.

The problem is that the rouge binaries (rougify), installed by gem are in a different path. This predicament is not present on FreeBSD/Linux because you are instructed to install everything with a package manager, which installs all the binaries in the same place.

I have deployed a simple GitHub repo illustrating this issue. It patches the Makefile. You can verify in the artifacts for each run that the documentation builds successfully (it uploads a documentation.zip file containing the public directory).

In the meantime, perhaps a quick solution would be to define:

ROUGIFY_CMD?= ${LOCALBASE}/bin/rougify

So it can be overridden:

$ bmake run ROUGIFY_CMD=${GEM_PATH}/rougify

My main issue with this patch are the symlinks.

This looks fine, but we have to make each if case for FreeBSD, Linux, and macOS. Unfortunately, I don't know how to make a variable of 'uname -s' in bmake. Is there such a way in bmake?

[jlduran_gmail.com]

In D37143#844015, @fel1x.mintchoco.development_gmail.com wrote:

In D37143#843876, @jlduran_gmail.com wrote:

I took a closer look at this, and I think one solution could be just to patch the Makekile in the documentation directory.

The problem is that the rouge binaries (rougify), installed by gem are in a different path. This predicament is not present on FreeBSD/Linux because you are instructed to install everything with a package manager, which installs all the binaries in the same place.

I have deployed a simple GitHub repo illustrating this issue. It patches the Makefile. You can verify in the artifacts for each run that the documentation builds successfully (it uploads a documentation.zip file containing the public directory).

In the meantime, perhaps a quick solution would be to define:

ROUGIFY_CMD?= ${LOCALBASE}/bin/rougify

So it can be overridden:

$ bmake run ROUGIFY_CMD=${GEM_PATH}/rougify

My main issue with this patch are the symlinks.

This looks fine, but we have to make each if case for FreeBSD, Linux, and macOS. Unfortunately, I don't know how to make a variable of 'uname -s' in bmake. Is there such a way in bmake?

FreeBSD and Linux users would not need to set ROUGIFY_CMD, as it would use the default ${LOCALBASE}/bin/rougify, this change would be transparent to them. Only macOS users would need to pass this environment variable to bmake, given $LOCALBASE is not the same as $GEM_PATH.

[jlduran_gmail.com]

documentation/content/en/books/fdp-primer/overview/_index.adoc

278

If you are not bothered by symlinking, why not just add these two and leave asciidoctor as it was (installed by Homebrew)?
I would guess that could be another possibility?

[jlduran_gmail.com]

Here is a branch on the same repo with the approach suggested by this diff of adding the symlinks (but just for ruby and rougify).

From the commit message:

Note that Homebrew explicitly does not create these symlinks:

> By default, binaries installed by gem will be placed into:
>   /usr/local/lib/ruby/gems/3.1.0/bin
>
> You may want to add this to your PATH.
>
> ruby is keg-only, which means it was not symlinked into /usr/local,
> because macOS already provides this software and installing another version in
> parallel can cause all kinds of trouble.

[minsoochoo0122_proton.me]

I uploaded wrong diff file. I'll fix in a few minutes

[minsoochoo0122_proton.me]

documentation/content/en/books/fdp-primer/overview/_index.adoc

278

I would like to install asciidoctor, asciidoctor-pdf, and asciidoctor-epub3. However, there is no ascidoctor-pdf and asciidoctor-epub3 on Homebrew. installing them via rubygem would be easier to manage.

[jlduran_gmail.com]

I prefer the direction this is heading to!
There is one thing that bothers me with the current diff, but it can be easily solved: If I a person is a FreeBSD user and a Ruby developer, the GEM_PATH might be already defined (see other reserved names).
Let's try to tackle this from the end user's perspective:
FreeBSD:

$ bmake run

Linux:

$ bmake run LOCALBASE=/usr

macOS:

$ bmake run USE_RUBYGEMS=YES GEM_PATH=/usr/local/lib/ruby/gems/[ruby_version]

If the macOS user has already defined GEM_PATH, then the command would just be bmake run USE_RUBYGEMS=YES. USE_RUBYGEMS or something along those lines.
Then, a FreeBSD/Linux user, that is also a Ruby developer —and hates installing Ruby gems via package managers— now has the ability to USE_RUBYGEMS.
What do you think?

documentation/content/en/books/fdp-primer/overview/_index.adoc

270

I was able to install these gems without sudoing using the tests runners on GitHub. Do you mind verifying?
The thing is, for me, on macOS:
sudo gem install ... means install a gem using the system's Ruby (i.e. the one that ships with macOS located on /usr/bin/ruby.
gem install ... means I have installed another version of Ruby that requires no root privileges to run (which we have, in this case).
I may be being a bit paranoid on this one, so disregard if you would.

278

Hmm, by looking at the formula, I thought it came with asciidoctor.

[minsoochoo0122_proton.me]

documentation/content/en/books/fdp-primer/overview/_index.adoc

278

I cannot find asciidoctor-epub3

[minsoochoo0122_proton.me]

In D37143#844449, @jlduran_gmail.com wrote:

I prefer the direction this is heading to!
There is one thing that bothers me with the current diff, but it can be easily solved: If I a person is a FreeBSD user and a Ruby developer, the GEM_PATH might be already defined (see other reserved names).
Let's try to tackle this from the end user's perspective:
FreeBSD:

$ bmake run

Linux:

$ bmake run LOCALBASE=/usr

macOS:

$ bmake run USE_RUBYGEMS=YES GEM_PATH=/usr/local/lib/ruby/gems/[ruby_version]

If the macOS user has already defined GEM_PATH, then the command would just be bmake run USE_RUBYGEMS=YES. USE_RUBYGEMS or something along those lines.
Then, a FreeBSD/Linux user, that is also a Ruby developer —and hates installing Ruby gems via package managers— now has the ability to USE_RUBYGEMS.
What do you think?

That sounds great. I'll modify Makefile

[minsoochoo0122_proton.me]

documentation/content/en/books/fdp-primer/overview/_index.adoc

270

I found out that we can use gem --user-install option. How do you think about this?

[jlduran_gmail.com]

This looks great! Give me some time to test it on all three platforms.
It may still need a few minor adjustments.
Thank you!

documentation/Makefile

38–44

Inverted logic here? (i.e. if USE_RUBYGEMS is YES then ... else ...).

41

Beware that GEM_PATH should already include /bin. Maybe ${GEM_PATH%/bin}?

44

I think Ruby binaries are not under GEM_PATH.

documentation/content/en/books/fdp-primer/overview/_index.adoc

261–263

I wonder if it should instruct the user to also set the GEM_PATH? Something like:

$ echo 'export GEM_PATH="/usr/local/lib/ruby/gems/3.1.0/bin"' >> ~/.zshrc
$ echo 'export PATH="$GEM_PATH:/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc

270

Don't worry. Let's leave it as it was. Thank you!

289

Although, if we instruct the user to add the GEM_PATH to the ~/.zshrc file, it can be omitted.

documentation/tools/asciidoctor.sh

34

39

[minsoochoo0122_proton.me]

documentation/Makefile

41

• GEM PATHS:
  • /usr/local/lib/ruby/gems/3.1.0
  • /usr/local/lib/ruby/gems/3.1.0/bin

It both includes /bin and its parent directory.

44

➜ where asciidoctor
/usr/local/lib/ruby/gems/3.1.0/bin/asciidoctor
/usr/local/opt/ruby/bin/asciidoctor
/usr/local/bin/asciidoctor

On macOS, it is under GEM_PATH.

➜ gem env
RubyGems Environment:

• RUBYGEMS VERSION: 3.3.24
• RUBY VERSION: 3.1.2 (2022-04-12 patchlevel 20) [x86_64-darwin21]
• INSTALLATION DIRECTORY: /usr/local/lib/ruby/gems/3.1.0

GEM_PATH/bin is also the installation directory.

documentation/content/en/books/fdp-primer/overview/_index.adoc

261–263

GEM_PATH does not include bin folder.

289

We don't need to add /bin here since Makefile adds it instead. But I'll remove GEM_PATH parameter in the example because the user already defined GEM_PATH in their ~/.zshrc

[minsoochoo0122_proton.me]

On macOS and Linux (I used Kali Linux), GEM_PATH is not /bin folder.

Therefore, when USE_RUBYGEMS is YES, GEMBASE becomes GEM_PATH. The program files installed by gem are installed in /bin folder, so for example, rougify is in $GEMBASE/bin folder, or $GEM_PATH/bin folder

[jlduran_gmail.com]

I have created a pull request with a rough sketch of what has been discussed here:
https://github.com/freebsd/freebsd-doc/pull/91
Please discard the Pull Request, it was used just to illustrate a point.
Thank you!

documentation/tools/asciidoctor.sh

34

Ignore this comment

[carlavilla]

I'm gonna take a look.
Everything works well on FreeBSD except PDF and EPUB3 commands.

[carlavilla]

Can you upload the patch again with this change? Works for you?
Using the if in this way works in FreeBSD.

documentation/tools/asciidoctor.sh

31

if [ "$USE_RUBYGEMS" = "YES" ]; then
GEMBASE="${GEM_PATH}"
else
GEMBASE="${LOCALBASE}"
fi

[carlavilla]

Approved.
I'm gonna commit it right now.
Thanks for this!