Need easy instructions for running "samples" commands

[devjgm]

In order to have a nice "getting started" page for C++ similar to this one for Java, we need some reasonably simple instructions for users can run the individual sample commands.

Some possible options:

1. Direct users to the INSTALL.md file and have them install the deps and compile all the spanner code. This is likely a lot of work for a "getting started" doc.

2. Use bazel. Bazel is pretty simple since it builds all the deps automatically. The downside is that most users do not use bazel, so they'd first need to go install bazel.

3. Use a Dockerfile where we can automate this. The downside is that users need to install docker if they don't already have it.

4. Use vcpkg. Users would need to install vcpkg if they don't already have it.

5. We host/provide a few statically linked, precompiled "samples" binaries. We'd need one for Windows, Mac, and Linux (at least). Users could then directly run these pre-compiled binaries when going through the "samples" exercises and they'd have nothing to compile themselves.

6. Some other script of some form??

7. .... ???

[devjgm]

/cc @mmmarklu

[mmmarklu]

Thanks for filing the issue.

Can you confirm one thing for me?

Running through the steps in INSTALL.md does not build an executable file based on samples.cc.

I want to confirm because when I ran sudo cmake --build folder --target install, the console said "Built target samples", which I assume was doing something with the various build files in the samples folder (BUILD, CMakeList, etc) but it looks like those are just building/running tests. Is that correct?

[devjgm]

Can you confirm one thing for me?

Running through the steps in INSTALL.md does not build an executable file based on samples.cc.

Yes, I think. If you look in the directory where all your cmake output files went -- it's probably called cmake-out/ -- you may see a binary named "samples" or something. Maybe find cmake-out -name '*sample*' and see what shows up.

Overall, though, I don't think the full set of "install" instructions are the right thing for the quick start web page. It's too involved and complex for a getting-started thing.

FTR, iff a user has bazel installed, they can compile and run the samples binary with a single command like this one (that works with my sample project/instance):

$ bazel run google/cloud/spanner/samples:spanner_client_samples -- create-database jgm-cloud-cxx jgm-spanner-instance samples

I'd like to get us closer to something like that. However, I suspect that few people have bazel installed, but maybe that's OK? We basically need to decide what is the easiest/best way to get users up and running quickly.

[coryan]

Can you confirm one thing for me?
Running through the steps in INSTALL.md does not build an executable file based on samples.cc.

Yes, I think. If you look in the directory where all your cmake output files went -- it's probably called cmake-out/ -- you may see a binary named "samples" or something. Maybe find cmake-out -name '*sample*' and see what shows up.

The executable is created in ${CMAKE_BINARY_DIR}/google/cloud/spanner/samples/samples, where CMAKE_BINARY_DIR is (if you follow the instructions) cmake-out/.

Overall, though, I don't think the full set of "install" instructions are the right thing for the quick start web page. It's too involved and complex for a getting-started thing.

FTR, iff a user has bazel installed, they can compile and run the samples binary with a single command like this one (that works with my sample project/instance):

$ bazel run google/cloud/spanner/samples:spanner_client_samples -- create-database jgm-cloud-cxx jgm-spanner-instance samples

I'd like to get us closer to something like that. However, I suspect that few people have bazel installed, but maybe that's OK? We basically need to decide what is the easiest/best way to get users up and running quickly.

If you only have CMake installed, then this will download all the dependencies (except OpenSSL), compile them and compile our code:

cmake -Hsuper -Bcmake-out
cmake --build cmake-out

The binary is then located in cmake-out/build/google-cloud-cpp-spanner/src/google-cloud-cpp-spanner-as-external-build/google/cloud/spanner/samples

We can make that path less horrible with some changes to the super/CMakeLists.txt file.

[ghost]

How about install the samples to something like $prefix/share/samples, which is a common location for such a thing. Then:

cmake -Hsuper -Bcmake-out/si -DCMAKE_BUILD_TYPE=Release \
                                                -DGOOGLE_CLOUD_CPP_EXTERNAL_PREFIX=$PWD/local-spanner -GNinja
cmake --build cmake-out/si
# Samples are in $PWD/local-spanner/share/samples

[coryan]

@remyabel I like the idea of installing the samples, though I think $prefix/share is usually reserved for files that are not architecture specific, so maybe $prefix/bin ?

[ghost]

Yes now I realized that it's common to distribute examples source code not precompiled binaries to $prefix/share. The instructions will just need an extra step:

# Paths may not be accurate
cmake -H$prefix/share/samples -Bcmake-out/samples -DCMAKE_PREFIX_PATH=$prefix/local-spanner

Then add a separate flag to compile examples (like g-c-cpp) to kill two birds with one stone. Or if that's too complicated just copy all the sample binaries to something like $PWD/samples.

[devjgm]

Tagging @antfitch who may be interested in following this issue.

[devjgm]

After a discussion offline, we're going to look into using bazel for this samples command. The reason being that it may be easier to get a command like bazel run ...:samples -- args to work on Linux, Windows, and Mac. Of course, there's a requirement that the user will need to first install bazel, which I think itself is fairly straight-forward.

Next steps:

• Propose the specific steps needed for a user to go from nothing to able to run the samples command. (Likely, clone the repo; install bazel; bazel run ...) There may be an extra step or caveat when running this on Mac/Windows. We'll need to document this.

• Add this documentation to the right place (TODO pick the Right Place)

• Add a CI build to make sure these steps continue to work.

[coryan]

• Propose the specific steps needed for a user to go from nothing to able to run the samples command. (Likely, clone the repo; install bazel; bazel run ...) There may be an extra step or caveat when running this on Mac/Windows. We'll need to document this.

• Add this documentation to the right place (TODO pick the Right Place)

I think README.md and spanner-main.dox are the right places (yes both).

• Add a CI build to make sure these steps continue to work.

We should change the ci/kokoro/readme/ builds to do this.