Wireshark · Wireshark-dev: Re: [Wireshark-dev] Building Wireshark 3.4.0 documentation on Windows

[Graham Bloice <graham.bloice@xxxxxxxxxxxxx>]

On Mon, 2 Nov 2020 at 16:34, John Dill <John.Dill@xxxxxxxxxxxxxxxxx> wrote:

>Message: 2
>Date: Mon, 2 Nov 2020 16:04:21 +0000
>From: Graham Bloice <graham.bloice@xxxxxxxxxxxxx>
>To: Developer support list for Wireshark <wireshark-dev@xxxxxxxxxxxxx>
>Subject: Re: [Wireshark-dev] Building Wireshark 3.4.0 documentation on
>        Windows
>Message-ID:
>        <CALcKHKqvsb4UFqtKox_Of73m68BZ=w=VAVVuN7b5B_xQopPqXw@xxxxxxxxxxxxxx>
>Content-Type: text/plain; charset="utf-8"
>
>On Mon, 2 Nov 2020 at 15:06, Maynard, Chris via Wireshark-dev <
>wireshark-dev@xxxxxxxxxxxxx> wrote:
>
> > > -----Original Message-----
> > > From: Wireshark-dev <wireshark-dev-bounces@xxxxxxxxxxxxx> On Behalf Of
> > > Gerald Combs
> > > Sent: Sunday, November 1, 2020 8:36 PM
> > > To: Developer support list for Wireshark <wireshark-dev@xxxxxxxxxxxxx>;
> > > Graham Bloice <graham.bloice@xxxxxxxxxxxxx>
> > > Subject: Re: [Wireshark-dev] Building Wireshark 3.4.0 documentation on
> > > Windows
> > >
> > > On 11/1/20 2:29 PM, Graham Bloice wrote:
> > > >
> > > > On Sat, 31 Oct 2020 at 18:42, Maynard, Chris via Wireshark-dev
> > <wireshark-
> > > dev@xxxxxxxxxxxxx <mailto:wireshark-dev@xxxxxxxxxxxxx>> wrote:
> > > >
> > > >     Section 2.2.8 of the Wireshark Developer’s Guide[1] instructs you
> > to install
> > > asciidoctor, xsltproc and docbook if you want to build the Wireshark
> > > documentation; however, it doesn’t specify the minimum version
> > requirements
> > > of those tools.
> > > >
> > > >     Attempting to build the documentation for the new 3.4.0 release
> > failed on
> > > my system.  Running "choco list --localonly" showed that I had these
> > relevant
> > > package versions installed:
> > > >
> > > >     asciidoctorj 2.1.0
> > > >     docbook-bundle 1.0.0
> > > >     xsltproc 1.1.28.0
> > > >
> > > >     … and running "choco outdated" revealed that asciidoctor was
> > outdated:
> > > >
> > > >     Chocolatey v0.10.15
> > > >     Outdated Packages
> > > >     Output is package name | current version | available version |
> > pinned?
> > > >
> > > >     asciidoctorj|2.1.0|2.3.0|false
> > > >
> > > >     I updated the asciidoctor package to version 2.3.0 and was able to
> > > successfully build the documentation.  (NOTE: I actually ran "choco
> > upgrade all"
> > > to upgrade all packages.)  In any case, if building the documentation
> > fails for
> > > you, you may want to check your installed versions and upgrade to the
> > latest
> > > available packages if any are outdated.
> > > >
> > > >     And perhaps the Developer’s Guide should mention minimum required
> > > versions, if possible?
> > > >
> > > >
> > > > I'm not sure about doing this, it's a never ending chase.
> > > >
> > > > I do agree that the CMake generation step could check minimum
> > > requirements.
> > >
> > > It does:
> > >
> > >     find_package( Asciidoctor 1.5 )
> > >
> > > 1.5.0 (released in 2014) and later support the "modern" syntax described
> > at
> > > https://asciidoctor.org/docs/migration/), which is what we currently
> > use in our
> > > documentation. I can successfully build the user_guides,
> > developer_guides, and
> > > release_notes targets here on an Ubuntu system with AsciiDoctor 1.5.5
> > > installed. Chris, do you remember what error(s) you ran into with
> > AsciiDoctorJ
> > > 2.1.0?
> >
> > Unfortunately, I don't have the exact error, but IIRC, it was some
> > non-intuitive, rather generic "Error 1" output or something.
> >
> > So perhaps it wasn't the asciidoctor upgrade that resolved the problem.
> > As I mentioned, some other packages were upgraded as well.
> >
> > Here's the list of packages and versions installed before the upgrade:
> > choco list --localonly
> > Chocolatey v0.10.15
> > apache-fop 2.2
> > asciidoctorj 2.1.0
> > autohotkey.portable 1.1.32.00
> > chocolatey 0.10.15
> > chocolatey-core.extension 1.3.5.1
> > docbook-bundle 1.0.0
> > easy.install 0.6.11.4
> > html-help-workshop 1.32
> > jre8 8.0.231
> > pip 1.2.0
> > python 3.7.5
> > python3 3.7.5
> > speex 1.0.4
> > strawberryperl 5.30.1.1
> > windbg 10.0.10586.15
> > winflexbison 2.4.9.20170215
> > xsltproc 1.1.28.0
> > 17 packages installed.
> >
> > And here are those that were determined to be outdated:
> > choco outdated
> > Chocolatey v0.10.15
> > Outdated Packages
> >  Output is package name | current version | available version | pinned?
> >
> > apache-fop|2.2|2.4|false
> > asciidoctorj|2.1.0|2.3.0|false
> > autohotkey.portable|1.1.32.00|1.1.33.02|false
> > easy.install|0.6.11.4|0.6.11.4|false
> > jre8|8.0.231|8.0.271|false
> > python|3.7.5|3.9.0|false
> > python3|3.7.5|3.9.0|false
> > strawberryperl|5.30.1.1|5.32.0.1|false
> >
> > Chocolatey has determined 7 package(s) are outdated.
> >  1 package(s) had warnings.
> > Warnings:
> >  - easy.install
> >
> > And here's the list of packages and versions after the upgrade (Note:
> > strawberryperl failed to update):
> > choco list --localonly
> > Chocolatey v0.10.15
> > apache-fop 2.4
> > asciidoctorj 2.3.0
> > autohotkey.portable 1.1.33.02
> > chocolatey-core.extension 1.3.5.1
> > chocolatey-windowsupdate.extension 1.0.2
> > docbook-bundle 1.0.0
> > easy.install 0.6.11.4
> > html-help-workshop 1.32
> > jre8 8.0.271
> > KB2919355 1.0.20160915
> > KB2919442 1.0.20160915
> > KB2999226 1.0.20181019
> > KB3033929 1.0.3
> > KB3035131 1.0.1
> > pip 1.2.0
> > python 3.9.0
> > python3 3.9.0
> > speex 1.0.4
> > strawberryperl 5.30.1.1
> > vcredist140 14.27.29112
> > vcredist2015 14.0.24215.20170201
> > windbg 10.0.10586.15
> > winflexbison 2.4.9.20170215
> > xsltproc 1.1.28.0
> > 24 packages installed.
> >
> >
> FWIW, Strawberry Perl has failed to update for me with chocolatey the last
> few versions, my workaround is to uninstall and then install again.
>
> There is a winflexbison3 package that has newer versions, and both nsis and
> wixtoolset are available as chocolatey packages.
>
> I don't think apache-fop or xsltproc are required now (I don't have them in
> my current VM's) and I've never installed speex.

I build on Windows primarily and I've had recent issues with Strawberry Perl
(as of 3.2.7, I haven't tried merging 3.4.0 yet into my local svn) giving an error
that using ActivePerl did not during the build process.  I recommend
trying ActivePerl instead of StrawberryPerl and see if the build issue resolves.

Strawberry Perl gave me an error that I couldn't quite figure out, so I just
tried ActivePerl.  It seemed to work so I didn't bother investigating further
since using ActivePerl seemed to workaround the Windows build issue.

I set the env var LC_ALL=C.UTF8 in my shell (PowerShell classic) so that git output is correctly displayed.  This causes StrawberryPerl to warn  about a few locale things so I inhibit those with the env var PERL_SKIP_LOCALE_INIT="0".

Apart from the Perl warnings as noted above that I suppress, the build runs perfectly fine on StrawberryPerl.

I'm still floating on a Cygwin based tweak to the typical Windows build
process for 3.2.7 since IT dept wouldn't "easily" allow Chocolatey for security
reasons so my build environment isn't the usual kind.  I'll have to try 3.4.0
sometime this week and see how it goes.

I have recommended for a very long time (decades!) to NOT mix Wireshark Windows dev and Cygwin.  Maybe it's better since the move to CMake, but we used to get no end of issues when a Cygwin binary was picked up instead of the win32 version, apart from all the Cygwin path conversions as well.

--

Graham Bloice