Freebsd doc cross-platform build

[minsoochoo0122_proton.me]

Summary

I figured out they way to build freebsd-doc on macOS and Linux

Test Plan

On macOS, building with bmake command works fine for hugo. (Tested Freebsd Handbook with images)

[bcr]

Adding Sergio, as I think this might interest him.
Having a way to build our docs on other platforms is nice and might bring in some new contributions.

documentation/content/en/books/fdp-primer/doc-build/_index.adoc

79

New sentence, new line.

222–223

New sentence, new line.

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

104

s/differeces/differences/

[ygy]

A thought: could we also mention that we need to install some dependencies and they may have different package names?

documentation/content/en/books/fdp-primer/doc-build/_index.adoc

79

difference*
space before "("

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

104

syntax*

[minsoochoo0122_proton.me]

Fixed typo

[minsoochoo0122_proton.me]

Can someone review or commit my new diff file?

[carlavilla]

I’ll take this. Thanks for the patch

[ygy]

This is indeed a good start, though I quickly tried it on Ubuntu and didn't have any luck - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=255804

@fel1x.mintchoco.development_gmail.com, did you have to do anything else to make it work, except for switching to use make?

[minsoochoo0122_proton.me]

On macOS, documentation works.

I putted the screenshot of terminal and the page of localhost:1313

[minsoochoo0122_proton.me]

Website also works fine

[ygy]

Ok, no objections to moving this forward - if we find more details for other platforms in the future, we can always improve it then.

[minsoochoo0122_proton.me]

Today, I tried on Linux. I succeeded on Red Hat 8 on VMware Fusion 12. However, I had to install bmake hugo through homebrew and asciidoctor, asciidoctor-pdf, rouge through gem. Also, I had to make symbolic links of programs because in those programs are not instlled in /usr/local/bin/. Maybe this works in some distributions but not for others. I will try on other Redhat derivatives, Debian derivatives, and SUSE derivatives in a near future.
Here are some screenshots.

[minsoochoo0122_proton.me]

bmake and hugo technically works on linux. However, many distributions don't install packages in /usr/local/bin, problem with permissons. On Redhat side, only RHEL works, not fedora. On Debian side, Ubuntu doesn't work. The problem is permission in both cases, but there are other problems when I run bmake with root.

[ygy]

In D30176#681498, @fel1x.mintchoco.development_gmail.com wrote:

bmake and hugo technically works on linux. However, many distributions don't install packages in /usr/local/bin, problem with permissons. On Redhat side, only RHEL works, not fedora. On Debian side, Ubuntu doesn't work. The problem is permission in both cases, but there are other problems when I run bmake with root.

Thanks for all the testing results! We indeed should make the doc project more accessible for more platforms, and am happy to continue the discussions somewhere else (any insights on https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=255804 ?).

Again, this revision looks good to me, and @carlavilla seems to already be taking care of it ;)

[minsoochoo0122_proton.me]

Can this revision can be applied now or I need other things to do?

[ceri]

I think doceng need to decide if this is a valid engineering goal, based on recent discussions.

[carlavilla]

if no other member of the Doceng has a problem. It remains valid.
I am preparing a patch related to compilation. Give me a couple more days and I'll take a look at this patch.

[blackend]

I see no problem in adding some guidance, e.g., installing bmake for non-BSDs system users. Though, IMHO, It would be better to have people using directly FreeBSD to do FreeBSD related work.

[minsoochoo0122_proton.me]

In D30176#719268, @carlavilla wrote:

if no other member of the Doceng has a problem. It remains valid.
I am preparing a patch related to compilation. Give me a couple more days and I'll take a look at this patch.

Thank you, after this patch is applied, I will work on changing Makefiles that can be compiled on mac and Linux without making links. And plus, I cannot find that https://reviews.freebsd.org/D30145 is adjusted. Can you check it please?

In D30176#719843, @blackend wrote:

I see no problem in adding some guidance, e.g., installing bmake for non-BSDs system users. Though, IMHO, It would be better to have people using directly FreeBSD to do FreeBSD related work.

I agree. That is the most perfect method to build FreeBSD documents. However, I'm trying to make FreeBSD for anyone in any case(or environment).

Thank you everyone for your help!

[blackend]

In D30176#719940, @fel1x.mintchoco.development_gmail.com wrote:

In D30176#719268, @carlavilla wrote:

if no other member of the Doceng has a problem. It remains valid.
I am preparing a patch related to compilation. Give me a couple more days and I'll take a look at this patch.

Thank you, after this patch is applied, I will work on changing Makefiles that can be compiled on mac and Linux without making links

I disagree with that point: it's already difficult to have something that works for our needs, adding compatibility for other OS will be source of more problems and will require to maintain the compatibility.

. And plus, I cannot find that https://reviews.freebsd.org/D30145 is adjusted. Can you >check it please?

In D30176#719843, @blackend wrote:

I see no problem in adding some guidance, e.g., installing bmake for non-BSDs system users. Though, IMHO, It would be better to have people using directly FreeBSD to do FreeBSD related work.

I agree. That is the most perfect method to build FreeBSD documents. However, I'm trying to make FreeBSD for anyone in any case(or environment).

VM are there for those who don't want to install FreeBSD. No need to add more complexity to our Makefiles.

[minsoochoo0122_proton.me]

In D30176#719989, @blackend wrote:

In D30176#719940, @fel1x.mintchoco.development_gmail.com wrote:

In D30176#719268, @carlavilla wrote:

if no other member of the Doceng has a problem. It remains valid.
I am preparing a patch related to compilation. Give me a couple more days and I'll take a look at this patch.

Thank you, after this patch is applied, I will work on changing Makefiles that can be compiled on mac and Linux without making links

I disagree with that point: it's already difficult to have something that works for our needs, adding compatibility for other OS will be source of more problems and will require to maintain the compatibility.

. And plus, I cannot find that https://reviews.freebsd.org/D30145 is adjusted. Can you >check it please?

In D30176#719843, @blackend wrote:

I see no problem in adding some guidance, e.g., installing bmake for non-BSDs system users. Though, IMHO, It would be better to have people using directly FreeBSD to do FreeBSD related work.

I agree. That is the most perfect method to build FreeBSD documents. However, I'm trying to make FreeBSD for anyone in any case(or environment).

VM are there for those who don't want to install FreeBSD. No need to add more complexity to our Makefiles.

I created a new differential. Let's discuss there

[ygy]

I think this can be committed first, and we could continue the cross-platform build discussion afterwards if more improvements can be made.

IMHO it is little effort with big advantages if we figure out how to build the doc on other platforms. The tools are platform-independent anyways, so this allows new contributors to jump in and fix things/existing contributors to work more freely. However, I object to the platform-dependent changes to the Makefiles. It sounds unnecessary and error-prone to me. What we could do is to make the required executables easier to configure, so we could just do bmake PYTHON=python3.9 HUGO=... run-local on other platforms.

[minsoochoo0122_proton.me]

In D30176#721864, @ygy wrote:

I think this can be committed first, and we could continue the cross-platform build discussion afterwards if more improvements can be made.

IMHO it is little effort with big advantages if we figure out how to build the doc on other platforms. The tools are platform-independent anyways, so this allows new contributors to jump in and fix things/existing contributors to work more freely. However, I object to the platform-dependent changes to the Makefiles. It sounds unnecessary and error-prone to me. What we could do is to make the required executables easier to configure, so we could just do bmake PYTHON=python3.9 HUGO=... run-local on other platforms.

I agree. We can talk about cross-platform build after we commit this revision.

[carlavilla]

With the new documentation portal we can build it in MacOS and GNU/Linux.

@fel1x.mintchoco.development_gmail.com do you have access to a MacOS?
I want to test it before submitting the change to the documentation and I don't have access right now to a MacOS.
I requested help to a friend of mine again but maybe with your help we can close this soon :)

[ygy]

I will run some tests on macOS as well and report here.

[carlavilla]

In D30176#769702, @ygy wrote:

I will run some tests on macOS as well and report here.

Great! Thanks!

So, please, can you install Hugo, AsciiDoctor, rougify and bmake? And then in the documentation folder:

make run

[minsoochoo0122_proton.me]

I've already tested 10 months ago.

[pauamma_gundo.com]

documentation/content/en/books/fdp-primer/doc-build/_index.adoc

80

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

104

[minsoochoo0122_proton.me]

This comment was removed by minsoochoo0122_proton.me.

[minsoochoo0122_proton.me]

My local git repo somehow disappeared but I managed to make a new diff based on current version. If I update this diff, it will be a mess because there has been some changes in these files during last few months. What should I do?

[minsoochoo0122_proton.me]

Updated anyway. It seems to work

[carlavilla]

@fel1x.mintchoco.development_gmail.com can you please prepare a section like this Add instructions to build the website using GNU/Linux ?

[minsoochoo0122_proton.me]

In D30176#779062, @carlavilla wrote:

@fel1x.mintchoco.development_gmail.com can you please prepare a section like this Add instructions to build the website using GNU/Linux ?

Yes I will prepare installation for apt and dnf

[carlavilla]

No, only for MacOS.
Thanks!

[minsoochoo0122_proton.me]

New version

[minsoochoo0122_proton.me]

I think I can integrate overlapping lines.

[minsoochoo0122_proton.me]

Deleted duplicated lines

[pauamma_gundo.com]

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

189–207

Merge with previous section, "macOS and GNU/Linux"?

[minsoochoo0122_proton.me]

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

189–207

Sorry. I forgot to delete it.

[carlavilla]

I just created another revision to handle the macOS addition.
It's here: https://reviews.freebsd.org/D34752
@fel1x.mintchoco.development_gmail.com if your ok with this new revision I'll commit it.
Are the instructions ok? I removed the brew installation command since the idea of this documentation it's to help the user to build the documentation in macOS not to install brew.

[minsoochoo0122_proton.me]

In D30176#787554, @carlavilla wrote:

I just created another revision to handle the macOS addition.
It's here: https://reviews.freebsd.org/D34752
@fel1x.mintchoco.development_gmail.com if your ok with this new revision I'll commit it.
Are the instructions ok? I removed the brew installation command since the idea of this documentation it's to help the user to build the documentation in macOS not to install brew.

You are right. It seems describing the installation process of Homebrew is unnecessary. It looks fine to commit.

[carlavilla]

Since I based my patch in your patch, I'll make the commit with the attribution to you :)

[carlavilla]

Committed