Installing CommonMark Perl Module on Windows 10

I wanted to use cmark, the C reference implementation of CommonMark. Building the library and the command line utility using Visual Studio tools is straightforward enough. Last time I checked, perl did not build with VS2015, so make sure to use the VS2013 tools (cl version 18.xx.xxxxx).

I install everything under c:\opt, so the command line tool and the DLLs go to C:\opt\bin, headers go to c:\opt\include, and the import and static libraries go to c:\opt\lib. After you do that, append the header and library locations to %INC%, and %LIB%, respectively.

Then, I did a:

C:\...\Temp> cpanm CommonMark

so I could use the library from Perl programs. I could have shelled out to the command line utility. It is pretty quick, but I wanted to do the proper thing.

CommonMark’s build process uses Devel::CheckLib to see if cmark.lib is installed. Unfortunately, Devel::CheckLib’s tests are a mess on Windows. I don’t have the patience to figure out the exact reason right now, but they fail hard. Update: Devel::CheckLib builds, installs, and works cleanly on Windows now. The problem turned out to be a rather small one, required a lot of squinting. It was obvious in hindsight.

So, I just ignored that (after submitting the result to CPANTesters). Instead, I switched to the build directory for the Perl module CommonMark (you can find it under .cpanm\work in your home directory), and deleted the library check from its Makefile.PL. This allowed me to successfully run perl Makefile.PL. Everything compiled fine. I hit another roadbump when it was time to compile, however:

C:\...\CommonMark-0.230002> nmake test
…
Test Summary Report
-------------------
t\08_create_helpers.t (Wstat: 256 Tests: 2 Failed: 1)
  Failed test:  2
  Non-zero exit status: 1

What’s going on?

C:\...\CommonMark-0.230002> prove -vb t\08_create_helpers.t
not ok 2 - create_* helpers#   Failed test 'create_* helpers'

#   at t\08_create_helpers.t line 104.
#          got: '<h2>Header</h2>
# <blockquote>
# <p>Block quote</p>
# </blockquote>
# <ol start="2">
# <li>Item 1</li>
# <li>Item 2</li>
# </ol>
# <pre><code class="language-perl">Code block</code></pre>
# <div>html</html>
# <hr />
# <p><em>emph</em>
# <a href="/url" title="link title"><strong>link text</strong></a><br />
# <img src="/facepalm.jpg" alt="alt text" title="image title" /></p>
# '
#     expected: '<h2>Header</h2>
# <blockquote>
# <p>Block quote</p>
# </blockquote>
# <ol start="2">
# <li>Item 1</li>
# <li>Item 2</li>
# </ol>
# <pre><code>Code block</code></pre>
# <div>html</html>
# <hr />
# <p><em>emph</em>
# <a href="/url" title="link title"><strong>link text</strong></a><br />
# <img src="/facepalm.jpg" alt="alt text" title="image title" /></p>
# '

I know it’s hard to see. The difference in the HTML output and the expected HTML is between:

# <pre><code class="language-perl">Code block</code></pre>

and

# <pre><code>Code block</code></pre>

respectively. To resolve which one is correct, we look at the test file, and note that the line is generated using:

CommonMark->create_code_block(
        fence_info => 'perl',
        literal    => 'Code block',
    ),

so, clearly, the output produced is in line with the code, and the expected output given in the test file is wrong. I understand how something like this may be overlooked. What I don’t understand are all the PASS results on CPANTesters. Could it be that cmark just recently started correctly generating code for this case? Again, I don’t have the patience to go down that rabbit hole right now. I put together a pull request, and moved on.

Update: It looks like this was not spotted due to the lack of diversity among the systems which were able to run the tests. The test results are from machines with similary configurations and with older versions of cmark.

The upshot is, you can safely ignore this test failure. The bug is not in the Perl module, or the library, but in the test script. If nothing else failed, just go ahead with nmake install, and enjoy!

You can discuss this post on r/perl.