[CXX-1070] Confusing installation instructions Created: 06/Oct/16  Updated: 13/Dec/16  Resolved: 08/Nov/16

Status: Closed
Project: C++ Driver
Component/s: Documentation
Affects Version/s: None
Fix Version/s: 3.1.0

Type: Bug Priority: Minor - P4
Reporter: David Golden Assignee: David Golden
Resolution: Done Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

Copied from notes on a Stackoverflow question so we don't lose track of it.

A couple notable issues:

The tutorial points to a specific file to fetch via curl rather than pointing to the github repository and suggesting doing a clone. This is a recipe for being a bit out of date. If I tell my infrastructure to fetch release 3.0.1, it will happily do that forever, rather than updating. That said, it appears that compiling from git is fine.
A prerequisite is installing libmongoc. It sure looks like installing from standard ubuntu packages is enough, since that's what the referenced page says. But the mongocxx installer wants >=1.3.4. So installing from git is required.
It depends on libbson >= 1.3.4, which is later than the ubuntu 16.04 installed version. So installing that, too, from git is required.
Note that none of the git packages specify which branch or tag to request in order to get a production build. Looking at all the tags on master and picking the numerically largest with no "rc" in the name seems to work. A tag called "release" or "current" would be oh-so-kind.
The build (typing make) tries to do a make install of the subpackage EP_mnmlstc_core, and this fails. So the entire build apparently has to run as root.
The example at the end of the tutorial presents build instructions that assume that everything you've done is somehow known to pkg-config, but the instructions never suggested how to make pkg-config aware of you. I just manually added cflags and ldflags. For me, that became this, although (warning) I'm still chasing down some symbols.

I see these specific issues to address:

  1. We need to provide a stable git reference for use in installation instructions. UPDATE: done
  2. We need to provide guidance on installing the correct versions of libmongoc, such as a git reference for installation. UPDATE: docs mention specific versions; opened CDRIVER-1904 to request permalink for stable tarball
  3. We need to document that the build ("make") stage tries to install install EP_mnmlstic_core by default; if this requires sudo (if the install directory is not owned by root) we need to mention that. (Separately, we should find a way to break those stages apart.) UPDATE: done
  4. We need to give better instructions on using pkg-config. UPDATE: doc patch ready


 Comments   
Comment by Githook User [ 08/Nov/16 ]

Author:

{u'username': u'xdg', u'name': u'David Golden', u'email': u'xdg@xdg.me'}

Message: CXX-1070 Improve installation instructions

Adds git download instructions pointing to release branches. Also
reminds people to be in 'build' and remember '..'.
Branch: 3.1-dev
https://github.com/mongodb/mongo-cxx-driver/commit/041cf76edebe3765d5d31ca47a40c9b5752b7fdc

Comment by Githook User [ 08/Nov/16 ]

Author:

{u'username': u'xdg', u'name': u'David Golden', u'email': u'xdg@xdg.me'}

Message: CXX-1070 Explain how to compile with/without pkg-config
Branch: 3.1-dev
https://github.com/mongodb/mongo-cxx-driver/commit/ade5d930f0f34ad1d6546c3001cf4fd047e387d2

Comment by David Golden [ 08/Nov/16 ]

Note: Doc update is now live on https://mongodb.github.io/mongo-cxx-driver/mongocxx-v3/installation/

Comment by David Golden [ 08/Nov/16 ]

We've improved the docs in several ways to address the original posters concerns.

Comment by Githook User [ 08/Nov/16 ]

Author:

{u'username': u'xdg', u'name': u'David Golden', u'email': u'xdg@xdg.me'}

Message: CXX-1070 Improve installation instructions

Adds git download instructions pointing to release branches. Also
reminds people to be in 'build' and remember '..'.
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/041cf76edebe3765d5d31ca47a40c9b5752b7fdc

Comment by Githook User [ 04/Nov/16 ]

Author:

{u'username': u'xdg', u'name': u'David Golden', u'email': u'xdg@xdg.me'}

Message: CXX-1070 Explain how to compile with/without pkg-config
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/ade5d930f0f34ad1d6546c3001cf4fd047e387d2

Comment by David Golden [ 03/Nov/16 ]

Moved to 3.1-desired as we won't actually be closing this ticket until after 3.0.3 ships.

Comment by David Golden [ 03/Nov/16 ]

I have commit to merge after 3.0.3 ships that gives some additional advice around doing without pkg-config. A draft is here: https://gist.github.com/xdg/bb201a464d1de69cda90b0870a2c371b

Comment by David Golden [ 03/Nov/16 ]

releases/stable will be created when we ship 3.0.3. We need to add it to the release notes, installation notes and release process description.

Comment by David Golden [ 18/Oct/16 ]

Updated manual page on installation to describe separate sudo install of mnmlstc in commit 21ea815.

Comment by David Golden [ 13/Oct/16 ]

For stable references, I suggest creating the following branches:

  • releases/stable @ r3.0.2
  • releases/legacy @ legacy-1.1.2

When we release 3.1.0-beta1 or 3.1.0-rc0, we can add a branch there as releases/unstable (or other term).

Generated at Wed Feb 07 22:01:18 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.