Doxygen in Docker Container Fails to Execute m2cpp.pl Filter Script Due to CRLF Issues

Have now fixed this. Thanks to those who replied. I shall try my best to recount all the steps below.

Version issues

Firstly, I built my own Docker image for Doxygen. I suspect the existing images on Docker Hub (corentinaltepe/doxygen, hrektts/doxygen) would have worked too, but I wanted full visibility for debugging. Here is the Dockerfile that I used to build my Docker image. It runs Doxygen 1.9.8 because that's the latest version available in the Ubuntu default package repository at present.

DOCKERFILECopied
FROM ubuntu:24.04

# Update
RUN apt-get update

# Install
RUN apt-get install -y vim doxygen graphviz

# Working directory
WORKDIR /doxygen/

I then generated a default Doxyfile from this version of Doxygen and changed the following settings. I think only the first two of these settings really matter, but I have included the remaining four for completeness and because they match the settings in the Doxyfile provided by Fabrice.

MAKEFILECopied
EXTENSION_MAPPING = .m=C++
FILTER_PATTERNS   = *.m=/doxygen/m2cpp.pl
EXTRACT_ALL       = YES
EXTRACT_PRIVATE   = YES
EXTRACT_STATIC    = YES
GENERATE_LATEX    = NO

Having made these changes, I was sure that I was using a relatively recent version of Doxygen. Moreover, I knew that my Doxyfile matched the version of Doxygen. Ie: it didn't contain deprecated settings etc. In hindsite, I don't think any of these version issues were actually causing the problem, but it was good practise to resolve them.

EOL issues

Secondly, I ran the following Git commands suggested here.

BASHCopied
git config core.autocrlf false
git rm --cached -r .
git reset --hard

Then I opened m2cpp.pl in VSCode and changed the End of Line (EOL) Sequence in from CRLF to LF. I had tried doing this previously but suspected Git was somehow preventing the change. On this second attempt, having run those three Git commands, the change was successful. I tested this by opening m2cpp.pl from Vim inside of an Ubuntu container and using :e ++ff=unix to show ^M carriage return characters, as suggested here. Sure enough, Vim showed that there were no ^M characters.

Shebang issues

Thirdly, I changed the first line of m2cpp.pl from #!/usr/bin/perl.exe to #!/usr/bin/perl. Apparently this is another Windows vs Unix thing. That first line tells the OS where to look for the Perl interpreter and Unix doesn't like the .exe suffix.

Testing locally

Having made these changes, I built and ran my Doxygen container locally by mounting it onto the folder that contained my Dockerfile, Doxyfile, m2cpp.pl and example MATLAB code in need of documentation.

BASHCopied
docker build doxygen-image .
docker run -it --mount type=bind,src=$pwd,dst=/doxygen/ doxygen-image

Since I ran the container in interactive mode -it, I was able to manually run commands in it. I ran the following commands inside of the /doxygen/ folder. The first one gives executable permission to m2cpp.pl and the second one runs Doxygen.

BASHCopied
chmod +x m2cpp.pl
doxygen Doxyfile

This produced HTML files containing the expected documentation. Very good.

Testing in pipeline

Finally, I needed to run all of this automatically inside of a BitBucket Pipeline. Here is the bitbucket-pipelines.yml file that I wrote for that. There are no new 'discoveries' here - it just implements the same steps as when I was testing locally. The two export commands are needed for building Docker images inside of a BitBucket Pipeline according to this thread. The command for running docker differs slightly from when I was testing locally. I don't entirely understand the difference, but the output seems to be the same. This automatically generates HTML documentation inside of the Pipeline. At present, I then manually download these files from BitBucket, but I shall configure this to instead send them to the server that will host the documentation.

YAMLCopied
image: docker:27.4.0

pipelines:
  default:
    - step:
        name: Doxygen
        script:
          # Give executable permission to Doxygen MATLAB filter
          - chmod +x m2cpp.pl

          # Build Docker image
          - export PATH=/usr/bin:$PATH
          - export DOCKER_BUILDKIT=1
          - docker build -f Dockerfile -t doxygen-image .

          # Run Docker container, mount pwd, run Doxygen, remove container
          - docker run --rm -v $(pwd):/doxygen/ doxygen-image /bin/bash -c "doxygen Doxyfile";
        artifacts:
          - html/**
        services:
          - docker