mapbox / mapbox/cpp

Add narrative documentation on how we do binary deployment

Open
#48 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
No language data
Stars
110
Forks
17
PR merge metrics
No merged PRs in 30d

Description

Now that our https://github.com/mapbox/cpp/blob/master/glossary.md is fairly complete, it is a good time to add new, narrative docs that tie together glossary terms.

In particular, there is a need for a binary deployment doc that explains the flow from C++ source code -> node addons -> binary distribution.

Here is a first stab at listing things to cover in this doc:

We use mason for:

- distributing [pre-compiled](https://github.com/mapbox/cpp/blob/master/glossary.md#precompiled) (aka binary) static libraries for C/C++ code. And in rare cases shared libraries.
- distributing source code of header-only libraries
- distributing binaries of [executables](https://github.com/mapbox/cpp/blob/master/glossary.md#executable) (aka command line programs).

We use node-pre-gyp for:

- Binary deployment of node C++ addons
- When those node C++ addons have external C/C++ dependencies we use mason to pull packages for them
- Soon we'll open source https://github.com/mapbox/mason-js which will make these more seamless (no need for the mason bash scripts)

TODO:

- integrate old node-pre-gyp docs into this repo and modify them to link to the glossary and this repo where appropriate. E.g. https://github.com/mapbox/node-pre-gyp/wiki/External-libraries, https://github.com/mapbox/node-pre-gyp/wiki/FAQ

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with glossary.md and the existing node-pre-gyp wiki pages for External-libraries and FAQ. Trace the documented flow from C++ source through node addons to binary distribution, covering mason and node-pre-gyp, then integrate the relevant old documentation into this repository with links to the glossary and related material.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, nodejs
Domain
build-system, documentation, release
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.