How should our build instructions be written?

[thejohnfreeman]

We currently have three open PRs touching our build instructions in a big way:

• Refactor build instructions #4381
• Update build instructions for Visual Studio 2019 #4394
• Revise Build Instructions #4423

I think they fundamentally disagree with each other on what the documentation should contain--its scope--and how it should be arranged--its structure. I think we should resolve that disagreement in this discussion before making further specific changes to the documentation itself. The principles we can establish in this discussion should make it clear exactly what should be written and where it should be placed, including what should be written by others elsewhere and merely linked by us here.

Audience

The build instructions have several different audiences, divided among several orthogonal dimensions:

• New vs experienced builders of rippled
• Builders for Linux, Mac, and Windows
• Builders using GCC, Clang, MSVC, or another compiler
• Builders using the default options vs customizations (reporting mode, sanitizers, unity build, etc.)

We should serve all audiences, but I think we should make it easy for experienced builders, who will be the most common builders, to find what they're looking for. In my mind, that means putting one-time-only introductory text at the end of BUILD.md, and including copy-pasteable commands for the default options and typical compilers on the major platforms. I don't think it's important to offer the same convenience to inexperienced builders, because they won't be inexperienced for long. I think it is reasonable to expect them to invest a little bit of time up-front to understand how the software is built instead of blindly skimming and copying every command in order.

Assumptions of reader experience

I would like to assume basic experience with the tools we demonstrate building rippled. We already assume experience with a shell, with CMake, and with how to install software on the reader's system. Our prior documentation included no introduction to CMake teaching readers to how to pass options, or choose a different compiler, or choose a generator. We recently introduced a new tool, Conan. I would like to assume basic familiarity with all of these tools, and to point to external documentation, at most, for those unfamiliar.

It was easy to assume familiarity with a shell and CMake because most people working with C++ are familiar with them. It's not as easy to assume familiarity with Conan because fewer C++ developers are familiar with it. I think it is reasonable to include our own short introduction to Conan, but I would like to make it external to BUILD.md.

Separate files

I do not want to maintain multiple, mostly identical sets of instructions for different platforms, like we tried in the past. I want one document with instructions for everyone, with minor deviations spelled out. It is easier to maintain, easier to link in answers, and easier for builders building in a new environment to notice the similarities and differences between them.

Scope

I want to include in BUILD.md:

• Copy-pasteable commands building rippled with default options, using recommended tools on supported platforms.
• Explanations of the different build options for rippled, e.g. static linkage, reporting mode, and sanitizers.
• Steps to troubleshoot common issues specific to building rippled, but not general tool issues like "how to reconfigure CMake" or "how to rebuild a dependency in Conan".
• Platform, compiler, and tool constraints, e.g. minimum versions.

I think there is a place in a separate document for instructions that are not part of building the software, e.g. for how to depend on xrpl_core from another CMake project. I think it might be reasonable to include instructions for installing rippled in BUILD.md, but I'd prefer they be separate too.

[justinr1234]

Agree with your Scope section with 1 caveat:

Common workflows, if expected, should be included. So if it's common to need to know "how to rebuild a dependency in Conan", then we should make it explicit and easy to understand (not require reading all the conan docs to then be able to do this standard operation rippled requires). For people who aren't constant contributors, it makes it tiresome to have to re-familiarize yourself with what rippled does in order to make a small contribution or be able to run a PR.

[justinr1234]

Thanks for talking the time, I agree with it being in a separate document. Only thing I’d add is maybe quickly linking out to that document along the way for any main file steps that could be confusing or potentially result in friction for new devs to the project.

[oeggert]

So we've got 4 docs planned, then?

1. Set up C++ dev environment.
2. Crash course and set up for CMake and Conan
3. Build Steps/Command
4. Install rippled/other post-build ops

[drlongle]

@thejohnfreeman I agree with your suggestion. Personally, I don't think we need to write about Git, CMake and Python. Some quick recipes for the big three platforms are sufficient in my opinion.

[thejohnfreeman]

@drlongle I don't think it makes sense to assume the reader knows how to install Git, CMake, and Python, but not a compiler, especially on Windows. I think if we're going to write for a reader who is new to C++ development, we should be complete. In the Linux and Mac instructions, I plan to include instructions for all tools.

@oeggert Mostly. I think it makes sense to separate the instructions for installation and dependence.

• BUILD.md: environmental constraints (e.g. compiler minimum versions), how to build rippled, link to environment.md
• docs/build/
  • environment.md: how to set up a C++ dev environment on the Big Three platforms
  • install.md: how to install rippled
  • depend.md: how to depend on xrpl_core
  • conan.md: crash course

[thejohnfreeman]

First phase of these changes has been submitted: #4381 (comment)

[oeggert]

I'm pretty much aligned with everything you've outlined here. I think it's better to keep installation and build instructions separate. Were you planning on having an installation md in the repo, or keeping the instructions we have on xrpl.org?

[thejohnfreeman]

I'd prefer it live in the repo because it is specific to rippled and not the XRPL, but I don't feel strongly.