building offline on Debian testing

[pfelecan]

Hello,

I'm trying to build an offline version on Debian testing (trixie) but it fails in the "jekyll" phase signaling a long list of gems to install which are not available or detected.

On which system the build is working ?

TIA

[nathan-contino]

It should work on Debian, but I'm not completely surprised to find an incompatibility. Try gem install bundler, then bundle install, and see if it gets you anywhere. The jekyll phase is supposed to automatically run those steps but it was never quite configured correctly on all environments.

[pfelecan]

In fact, the issue is with installing some ruby gems, e.g. colorator which is the version on rubygems.org but whatever I do it doesn't install. Maybe a transient error, I'll try later.

[pfelecan]

Indeed, a lot of wrangling with bundle install and gem install brings me further but at terminal-table gem it blocks because there is an version incompatibility in the Gemfile.lok which mention (>= 1.8, < 4.0) and terminal-table (3.0.2) which are no more available: the current version on rubygems.org is 4.0.0 IMHO, this wasn't tested for a long time. Now I need to find how to update the Gemfile.lock What a hurdle for somebody not familiar with the ruby ecosystem :-(

[lurch]

IMHO, this wasn't tested for a long time.

This gets "tested" every time that https://www.raspberrypi.com/documentation/ gets updated. See https://github.com/raspberrypi/documentation/blob/develop/.github/workflows/build.yml

If you're going to choose to use Debian "testing" rather than Debian "stable", you have to expect things to fail? 😕

[pfelecan]

This fail also on Debian stable as the issue is that the dependency for jekyll is incorrect regarding what can be obtained as gem for terminal table; nothing to do with Debian's version, isn't it ?

[lurch]

There were a couple of steps missing from https://github.com/raspberrypi/documentation/blob/develop/CONTRIBUTING.md which I've just created #4045 to fix, but I was successfully able to follow those instructions to build a local version the documentation on Raspberry Pi OS (which is based on Debian Bookworm).

[pfelecan]

I followed the steps described in the contribution file in order to build the documentation but I still get the error relative to the terminal-table version unavailability:

Fetching gem metadata from https://rubygems.org/.........
Using rake 13.2.1
Using base64 0.2.0
Using public_suffix 6.0.1
Using asciidoctor 2.0.23
Using bundler 2.3.22
Using bigdecimal 3.1.9
Using colorator 1.1.0
Using concurrent-ruby 1.3.5
Using csv 3.3.2
Using eventmachine 1.2.7
Using http_parser.rb 0.8.0
Using ffi 1.17.1 (x86_64-linux-gnu)
Using forwardable-extended 2.6.0
Using rb-fsevent 0.11.2
Using json 2.9.1
Using rexml 3.4.0
Using liquid 4.0.4
Using mercenary 0.4.0
Using rouge 4.5.1
Using safe_yaml 1.0.5
Using unicode-display_width 2.6.0
Using webrick 1.9.1
Using racc 1.8.1
Using temple 0.10.3
Using tilt 2.3.0
Using thread_safe 0.3.6
Using asciidoctor-tabs 1.0.0.beta.6
Using google-protobuf 4.29.3 (x86_64-linux)
Using addressable 2.8.7
Using i18n 1.14.7
Using em-websocket 0.5.3
Using rb-inotify 0.11.1
Using pathutil 0.16.2
Using kramdown 2.5.1
Using nokogiri 1.18.2 (x86_64-linux-gnu)
Using slim 5.2.1
Using sass-embedded 1.83.4 (x86_64-linux-gnu)
Using listen 3.9.0
Using kramdown-parser-gfm 1.1.0
Using jekyll-sass-converter 3.1.0
Using jekyll-watch 2.2.1
Bundler::GemNotFound: Could not find terminal-table-3.0.2.gem for installation
/var/lib/gems/3.3.0/gems/bundler-2.3.22/lib/bundler/source/rubygems.rb:159:in
install' /var/lib/gems/3.3.0/gems/bundler-2.3.22/lib/bundler/installer/gem_installer.rb:54:in install'
/var/lib/gems/3.3.0/gems/bundler-2.3.22/lib/bundler/installer/gem_installer.rb:16:in
install_from_spec' /var/lib/gems/3.3.0/gems/bundler-2.3.22/lib/bundler/installer/parallel_installer.rb:186:in do_install'
/var/lib/gems/3.3.0/gems/bundler-2.3.22/lib/bundler/installer/parallel_installer.rb:177:in
block in worker_pool' /var/lib/gems/3.3.0/gems/bundler-2.3.22/lib/bundler/worker.rb:62:in apply_func'
/var/lib/gems/3.3.0/gems/bundler-2.3.22/lib/bundler/worker.rb:57:in block in process_queue' <internal:kernel>:187:in loop'
/var/lib/gems/3.3.0/gems/bundler-2.3.22/lib/bundler/worker.rb:54:in
process_queue' /var/lib/gems/3.3.0/gems/bundler-2.3.22/lib/bundler/worker.rb:91:in block (2
levels) in create_threads'

An error occurred while installing terminal-table (3.0.2), and Bundler cannot
continue.

In Gemfile:
jekyll-asciidoc was resolved to 3.0.1, which depends on
jekyll was resolved to 4.4.1, which depends on
terminal-table

[lurch]

I followed the steps described in the contribution file in order to build the documentation...

As I mentioned yesterday, it works perfectly fine on Raspberry Pi OS, which is based on Debian Bookworm. Perhaps the difference you're seeing is because of the different Ruby version in Debian testing? 🤷‍♂ On Raspberry Pi OS I see:

$ ruby --version
ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [aarch64-linux-gnu]
$ gem --version
3.3.15

Bundler::GemNotFound: Could not find terminal-table-3.0.2.gem for installation

Seems to still be there at https://rubygems.org/gems/terminal-table/versions/3.0.2 ?

Also, from the Raspberry Pi OS installation on which I did the fresh documentation build yesterday:

$ ls .local/share/gem/ruby/3.1.0/gems/
addressable-2.8.7                     kramdown-parser-gfm-1.1.0
asciidoctor-2.0.23                    liquid-4.0.4
asciidoctor-tabs-1.0.0.beta.6         listen-3.9.0
base64-0.2.0                          mercenary-0.4.0
bigdecimal-3.1.9                      minima-2.5.2
bundler-2.3.22                        mini_portile2-2.8.8
bundler-2.6.5                         nokogiri-1.18.2
colorator-1.1.0                       pathutil-0.16.2
concurrent-ruby-1.3.5                 public_suffix-6.0.1
csv-3.3.2                             racc-1.8.1
em-websocket-0.5.3                    rake-13.2.1
eventmachine-1.2.7                    rb-fsevent-0.11.2
ffi-1.17.1                            rb-inotify-0.11.1
forwardable-extended-2.6.0            rexml-3.4.0
google-protobuf-4.29.3-aarch64-linux  rouge-4.5.1
http_parser.rb-0.8.0                  safe_yaml-1.0.5
i18n-1.14.7                           sass-embedded-1.83.4
jekyll-4.4.1                          slim-5.2.1
jekyll-asciidoc-3.0.1                 temple-0.10.3
jekyll-feed-0.17.0                    terminal-table-3.0.2
jekyll-sass-converter-3.1.0           thread_safe-0.3.6
jekyll-seo-tag-2.8.0                  tilt-2.3.0
jekyll-watch-2.2.1                    unicode-display_width-2.6.0
json-2.9.1                            webrick-1.9.1
kramdown-2.5.1

I'm going to close this issue, because I've demonstrated that it does still work, and we can't be expected to support "testing" versions of Linux distributions. 🐧

[pfelecan]

From ruby, and gem, point of view you're right.

$ ruby --version
ruby 3.3.7 (2025-01-15 revision be31f993d7) [x86_64-linux-gnu]
$ gem --version
3.6.3

However, if you search the terminal-table package on rubygems.org, the only available version is 4.0.0
But, I imagine that what the bundler gets depends on its version; well, as you can understand, ruby and other gems are not my cup of tea :-)

[pfelecan]

BTW, I do not understand what's "not planned" in the reason of closing this issue.
Eventually, the project will not build on the future Debian version.
Anyhow, as the owner of the project you can do what suits you.

[lurch]

Feel free to give this a try on Debian Bookworm, and if you still can't get it working then I'll re-open the issue and do further investigation.

[lurch]

Eventually, the project will not build on the future Debian version.

...or it might be a bug in the testing version of Debian, which will get fixed before it becomes stable? 🤷‍♂

[pfelecan]

I installed a Debian stable, i.e. bookworm, and followed the steps in CONTRIB.MD
After running make html I got the following:

...
[637/637] scripts/create_htaccess.py documentation/htaccess_extra.txt documentation/redirects build/jekyll/.htaccess
bundle exec jekyll build
Configuration file: /ICU/raspberry/documentation/_config.yml
            Source: /ICU/raspberry/documentation/build/jekyll
       Destination: /ICU/raspberry/documentation/documentation/html
 Incremental build: disabled. Enable with --incremental
      Generating... 
       Jekyll Feed: Generating feed for posts
DEPRECATION WARNING [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.

More info and automated migrator: https://sass-lang.com/d/import

  ╷
1 │ @import "minima";
  │         ^^^^^^^^
  ╵
    /ICU/raspberry/documentation/build/jekyll/assets/main.scss 1:9  root stylesheet
                    done in 5.654 seconds.
 Auto-regeneration: disabled. Use --watch to enable.
(.env) peter@0f32f4d618d9:/ICU/raspberry/documentation# echo $?
0

Is this nominal ?

BTW, there are some adjustments to made in the CONTRIBUTING.MD:

1. Install python3: apt-get install python3
2. When creating the virtual environment: python -m venv .env

[nathan-contino]

Expected behaviour. We need to migrate from the @import rules eventually but haven't gotten round to it yet. The build should work fine otherwise.