search

justinmeiners / efficient-programming-with-components

Course notes for Alexander Stepanov's teachings on design and usage of C++ STL.
https://www.jmeiners.com/efficient-programming-with-components/
75 stars 6 forks source link

add wrapper script to run build.sh inside docker #7

Closed aharrison24 closed 3 years ago

aharrison24 commented 3 years ago

It took me quite a while to figure out that 'discount' was the markdown tool used in the build process. I've added documentation to build.sh noting what its dependencies are.

I've also provided a wrapper script that provisions a docker container with the correct dependencies and runs the build script. Hopefully this will make it easier for others to submit corrections to the text and rebuild the html files.

justinmeiners commented 3 years ago

Thanks for the contribution. I am undecided whether I want to use docker, but I do want to better find and communicate which dependencies are needed. What distro do you use?

aharrison24 commented 3 years ago

I'm actually on MacOS and it turns out that both dependencies are provided in Homebrew. But before I'd figured out that I needed the 'discount' package rather than 'markdown' or 'multimarkdown' etc... I'd wondered if perhaps there were different versions of the 'markdown' script available on other distros. It took quite a lot of experimentation to find a working solution.

On Ubuntu Bionic the version of the discount package is too old and it makes substantial changes to all of the html files. Ubuntu Focal was the first distro I found that had a new enough version available by default.

I'm not a great fan of docker either. I just thought that some people might appreciate a relatively 'painless' way of satisfying the dependencies. My thinking was that providing it in a wrapper script would make it optional. Those who know how to provide the dependencies by some other means can still use build.sh directly.

One alternative would be to add a section in the README that contains instructions for a few key distros, and maybe lists the two docker commands for those that can't easily get the right package versions on their distro.

I guess ideally the html files would not be checked in to the repo but generated and pushed to the gh-pages branch by a CI stage. Then this would no longer be an issue for contributors to deal with.

justinmeiners commented 3 years ago

The build script now checks that the dependencies are correct.

docker container

I modified your script. I used alpine (smaller download). Also there was an issue where it changed the owner of all outputted files to root. I imagine on mac this didn't happen.

I'm not a great fan of docker either

Sure, no harm in including a several line script.

One alternative would be to add a section in the README that contains instructions for a few key distros.

Done.

I guess ideally the html files would not be checked in to the repo but generated and pushed to the gh-pages branch by a CI stage. Then this would no longer be an issue for contributors to deal with.

My friend Ryan agrees with you, but I tend to prefer to keep these things as simple as possible. It's a pretty simple build setup, and I'm happy to make fixes for contributors.

Since I copied your script, I am going to close this MR, but it is considered merged.