Page MenuHomeFreeBSD

Freebsd doc cross-platform build
ClosedPublic

Authored by fel1x.mintchoco.development_gmail.com on May 8 2021, 2:10 PM.

Details

Reviewers
carlavilla
ygy
pauamma
Group Reviewers
docs
doceng
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)

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

bcr added a subscriber: 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/

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*

Can someone review or commit my new diff file?

I’ll take this. Thanks for the patch

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?

On macOS, documentation works.

Screen Shot 2021-05-17 at 3.57.14 PM.png (2×5 px, 2 MB)

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

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

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.

Screen Shot 2021-05-18 at 11.52.07 PM.png (1×2 px, 820 KB)

Screen Shot 2021-05-18 at 11.50.36 PM.png (1×2 px, 766 KB)

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.

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 ;)

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

ceri added a subscriber: ceri.

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

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.

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.

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?

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!

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?

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.

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?

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

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.

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.

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 :)

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

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

pauamma added inline comments.
documentation/content/en/books/fdp-primer/doc-build/_index.adoc
80
documentation/content/en/books/fdp-primer/overview/_index.adoc
104

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?

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

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

fel1x.mintchoco.development_gmail.com marked an inline comment as done.
documentation/content/en/books/fdp-primer/overview/_index.adoc
189–207

Sorry. I forgot to delete it.

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.

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.

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

This revision is now accepted and ready to land.Apr 2 2022, 4:47 PM