#574: add instructions about how to build with Bazel

[iblancasa]

Fixes #574

Changes

Add some instructions about how to build with Bazel.

[lalitb]

Thanks @iblancasa for the PR. We can get some feedback from @eyjohn and @jsuereth also here. As @eyjohn had some plans to reorganize the build/install document for cmake and bazel.

[codecov]

Codecov Report

Merging #747 (1d2d9bf) into main (a6bd648) will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #747      +/-   ##
==========================================
+ Coverage   96.00%   96.01%   +0.01%     
==========================================
  Files         176      176              
  Lines        7183     7183              
==========================================
+ Hits         6896     6897       +1     
+ Misses        287      286       -1     

Impacted Files	Coverage Δ
sdk/src/logs/batch_log_processor.cc	95.00% <0.00%> (+1.25%)	⬆️

[maxgolov]

Technically the exclusion here -//exporters/otlp/... - isn't right. It all builds in its entirety right now, including otlp - which is going to be the main thing. Helper script for windows:

opentelemetry-cpp/tools/build-bazel.cmd

Line 4 in 414a731

bazel.exe build %* //...

[ThomsonTan]

How about just invoke tools/buildbazel.cmd here which will keep both consistent?

[maxgolov]

Maybe we need to add a script for Linux then, like tools/build-bazel.sh . But I actually like this document too.

[maxgolov]

I think you should be good to re-add otlp exporter. If you fix that, it looks good then. Approved with suggestion.

[maxgolov]

Suggested change

	bazel build -- //... -//exporters/otlp/... -//exporters/prometheus/...
	bazel build //...

[maxgolov]

OTLP-gRPC takes forever to build though 😄 (293s total on my docker container with WSL2)

[maxgolov]

CI / markdown-lint (pull_request) Failing after 7s — markdown-lint

Please run the linter locally (you can see how it's running in yaml action), fix whatever issues, and submit the resulting cleaned-up markdown.

[maxgolov]

Can we somehow omit 3.7.2. here. It's 10 seconds to follow the guidelines, even if we don't mention the version explicitly. Maybe suggesting to check what version is being used indirectly, by lookup up the file contents here:

opentelemetry-cpp/.bazelversion

Line 1 in 414a731

3.7.2

Something like: Please install the exact version of bazel mentioned in .bazelversion ?

mgolovanov@xps:/mnt/c/work/opentelemetry-cpp.main$ bazel build //...
ERROR: The project you're trying to build requires Bazel 3.7.2 (specified in /mnt/c/work/opentelemetry-cpp.main/.bazelversion), but it wasn't found in /usr/bin.

You can install the required Bazel version via apt:
  sudo apt update && sudo apt install bazel-3.7.2

Even if someone messes it up like I did, it takes 10 seconds to correct it - it even tells how to correct / install the right version. I think we might be upgrading the Bazel soon anyways, so probably not worth it anchoring to specific version in the how-to doc.

@jsuereth

[jsuereth]

Yeah, I think we should likely encourage folks to install/use Bazelisk, as it can auto-correct versions on the fly and leads to a much smoother developer experience when you move back/forth between different bazel projects.

[eyjohn]

Thanks for this contribution, it covers the process well.

I still have (slow) plans to restructure the install/usage docs focused on using otel-cpp in projects (which may/not include installing it) but I think this will build on top of these base instructions.

[lalitb]

@iblancasa - This is good to merge once the CI check for markdown lint is fixed. CI uses markdownlint-cli to validate the document using this configuration.

[jsuereth]

One meta question on instructions, otherwise, thanks much for taking a crack at this!

[jsuereth]

Isn't this more useful for contributors, less so installation?

E.g. I'd expect most bazel users to want to do something like pulling in OTel CPP via WORKSPACE definition using http_archive or some other mechanism.

Not that this isn't useful, just not how I'd expect folks to consume.

[jsuereth]

e.g. https://github.com/GoogleCloudPlatform/opentelemetry-operations-cpp/blob/main/WORKSPACE#L46

Or you can see:

https://github.com/googleapis/google-cloud-cpp/pull/1230/files for an example usage of OpenCensus C++

[lalitb]

This is a good point. We can have a separate section (say) "Incorporating Into An Existing Project", which includes the above-mentioned steps, similar to how we document for CMake.

[lalitb]

@iblancasa - we would like to pull these changes in. But the markdown-lint check is failing for now. Once you fix that, we can merge the changes.

[lalitb]

@iblancasa - I have fixed the lint error in your branch, and will be merging now. Hope this is fine :)