Page MenuHomeFreeBSD

Freebsd doc cross-platform build
Needs ReviewPublic

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

Details

Reviewers
carlavilla
ygy
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
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
55

New sentence, new line.

131–132

New sentence, new line.

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

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
55

difference*
space before "("

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

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.


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.


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.