Jupyter-book: Problems with local build instructions on Mac (and perhaps other 'nix platforms)

[mwcraig]

It turns out that the instructions for doing local builds ( at least on a Mac) don't work. The steps I've gone through so far to make progress (with links to some of the relevant roadblocks) are:

• Install command line tools (xcode-select --install) (may not be necessary depending on how recent your last OS update was).
• Update gem itself (see this in-progress update to the jupyter-book instructions, which includes a link to a statement from the bundler folks and an answer on stackoverflow). THIS IS NOT MAC-SPECIFIC
• Install the conda compilers for mac: conda install clangxx_osx-64 (see https://stackoverflow.com/questions/47314899/how-to-avoid-clang-no-such-file-or-directory-error). My hunch is that something like this is needed on linux too.
• On 10.14/Mojave, make the standard headers show up in the standard places because apple just had to move them.

Once that stuff is done, make install proceeds much farther, until it gets to building eventmachine, which uses openssl, and it can't find the headers for that:

./project.h:119:10: fatal error: 'openssl/ssl.h' file not found
#include <openssl/ssl.h>
         ^~~~~~~~~~~~~~~

That led me to this anaconda issue about building gems. I tried the monkey patch at https://github.com/ContinuumIO/anaconda-issues/issues/9863#issuecomment-460512146 but it didn't do the trick for me.

Will continue trying for a little bit longer and report back if I get something to work.

[mwcraig]

Success, sort of....

In addition to the monkey patch I linked to above, I had to add this to CPPFLAGS in rbconfig.rb:

-I/Users/mattcraig/anaconda3/anaconda/envs/ccd-guide/include

I think there are a couple of other places I could have stuck that.

Let me know if you want me to write this up into install instructions.

[choldgraf]

holy moly, thanks for all of this information. @emdupre you may be interested in this too in thinking about whether we should try to use something that's less of a hassle like hugo instead of jekyll

[choldgraf]

another quick question for you: it seemed like the ruby gems header problem wasn't present when using Ruby installed with conda-forge...did you double-check that this is the version of ruby you're using?

[mwcraig]

I was using the version from defaults, can try with the conda-forge version in a fresh environment if you want:

~/a/a/e/c/l/r/2/x86_64-darwin14 $ conda list ruby                                                                                                                                           (ccd-guide)
# packages in environment at /Users/mattcraig/anaconda3/anaconda/envs/ccd-guide:
#
# Name                    Version                   Build  Channel
ruby                      2.5.1                h74228e1_0

[choldgraf]

@mwcraig if conda-forge doesn't work, could you try with brew since you're on a mac? We will figure this out one way or another :-)

[mwcraig]

@choldgraf -- with just a touch of modification things seem to work with the conda-forge ruby. The twist is that the compilers either need to be installed before ruby or the ruby version needs to be pinned because the version on main is a more recent version than the one on conda-forge.

So this should work:

conda install -c conda-forge clangxx_osx-64
conda install -c conda-forge ruby

OR

conda install -c conda-forge ruby=1.4.5 clangxx_osx-64

It may still be necessary to do the header thing on OSX...I'm not sure because I don't know how to undo the header installation and didn't want to risk breaking things by deleting stuff from /usr/include 😀

[emdupre]

Thanks for the tip, @mwcraig ! It sounds like you've gotten it all working now ?

We're starting to add Docker installation instructions in #127 to hopefully avoid some of these installation headaches. We'd really appreciate your feedback there, if you're interested !

Either way, thanks again for keeping us updated -- happy to hear it seems to be working :sparkles:

[mwcraig]

Yep, it is all working now.

You should add installation of the conda-forge compilers to the install instructions for mac/linux because both platforms will need them.

[choldgraf]

@mwcraig that's a good point - would you mind opening an issue about it so that we don't lose that point? Would also love to hear your thoughts over in #83 if you've got any :-)

[mwcraig]

To wrap this up, these steps worked for me in a clean environment on a system on which I had upgraded to mojave fairly recently (so the headers are not in the standard places); it ends being simpler than what I originally reported. The first two steps will be necessary on mac and linux. The list step should be needed only on OSX 10.14 or later:

# Line below should change for linux...
conda install clangxx_osx-64
conda install -c conda-forge ruby

# OSX 10.14+ only:
open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg

[mwcraig]

Can open a PR to the instructions for this Wednesday am....

[choldgraf]

@mwcraig please do! improvements here are most-welcome :-)