<commit_before>= Protobuf Code Generation

:toc:
:toc-placement!:

toc::[]


[[intro]]
Introduction
------------

This example shows how to generate class information using https://github.com/google/protobuf[protobuf].
Protocol Buffers is a data serialization format from Google. A user provides a
`.proto` file with a description of the data. Then using the protobuf compiler, the proto file
can be translated into source code in a number of languages including C++.

The files in this tutorial are below:

```
$ tree
.
├── AddressBook.proto
├── CMakeLists.txt
├── main.cpp
```

  * AddressBook.proto - proto file from main protocol buffer https://developers.google.com/protocol-buffers/docs/cpptutorial[example]
  * CMakeLists.txt - Contains the CMake commands you wish to run
  * main.cpp - The source file from the protobuf example.

[[requirements]]
Requirements
~~~~~~~~~~~~

This example requires the protocol buffers binary and libraries to be installed.

This can be installed on Ubuntu using

```
sudo apt-get install protobuf-compiler sudo apt-get install protobuf-compiler
```

[[concepts]]
Concepts
~~~~~~~~

[[exported_variables]]
Exported Variables
^^^^^^^^^^^^^^^^^^

The variables exported by the CMake protobuf package and used in this example include:

  * `PROTOBUF_FOUND` - If Protocol Buffers is installed
  * `PROTOBUF_INCLUDE_DIRS` - The protobuf header files
  * `PROTOBUF_LIBRARIES` - The protobuf library

More variables are defined and can be found by examining the documentation at the
top of your `FindProtobuf.cmake` file.

[[generating-protobuf]]
Generating Source
^^^^^^^^^^^^^^^^^

The protobuf CMake package, includes a number of helper functions to make the
code generation easier. In this example we are generating C++ source and use
the following code:

[source,cmake]
----
PROTOBUF_GENERATE_CPP(PROTO_SRCS PROTO_HDRS AddressBook.proto)
----

The arguments are:

  * PROTO_SRCS - Name of the variable that will store the .pb.cc files.
  * PROTO_HDRS- Name of the variable that will store the .pb.h files.
  * AddressBook.proto - The .proto file to generate code from.

[[generated-files]]
Generated Files
^^^^^^^^^^^^^^^

After the `PROTOBUF_GENERATE_CPP` function is called, you will have the above
mentioned variables available. These will be marked as the output to a custom command
which calls the protobuf compiler binary to generate them.

To then have the files generated you should add them to a library or executable.
For example:

[source,cmake]
----
add_executable(protobuf_example
    main.cpp
    ${PROTO_SRCS}
    ${PROTO_HDRS})
---

This will cause the protobuf compiler to be called when you call `make` on that
executables target.

When changes are made to the .proto file, the associated source files will be
autogenerated again. However, if no changes are made to the .proto file and you re-run
make, then nothing will be done.

[[building-the-example]]
Building the Example<commit_msg>Fix adoc syntax issue from issue #1<commit_after>= Protobuf Code Generation

:toc:
:toc-placement!:

toc::[]


[[intro]]
Introduction
------------

This example shows how to generate source files using https://github.com/google/protobuf[protobuf].
Protocol Buffers is a data serialization format from Google. A user provides a
`.proto` file with a description of the data. Then using the protobuf compiler, the proto file
can be translated into source code in a number of languages including C++.

The files in this tutorial are below:

```
$ tree
.
├── AddressBook.proto
├── CMakeLists.txt
├── main.cpp
```

  * AddressBook.proto - proto file from main protocol buffer https://developers.google.com/protocol-buffers/docs/cpptutorial[example]
  * CMakeLists.txt - Contains the CMake commands you wish to run
  * main.cpp - The source file from the protobuf example.

[[requirements]]
Requirements
~~~~~~~~~~~~

This example requires the protocol buffers binary and libraries to be installed.

This can be installed on Ubuntu using

[source,bash]
----
sudo apt-get install protobuf-compiler sudo apt-get install protobuf-compiler
----

[[concepts]]
Concepts
~~~~~~~~

[[exported_variables]]
Exported Variables
^^^^^^^^^^^^^^^^^^

The variables exported by the CMake protobuf package and used in this example include:

  * `PROTOBUF_FOUND` - If Protocol Buffers is installed
  * `PROTOBUF_INCLUDE_DIRS` - The protobuf header files
  * `PROTOBUF_LIBRARIES` - The protobuf library

More variables are defined and can be found by examining the documentation at the
top of your `FindProtobuf.cmake` file.

[[generating-protobuf]]
Generating Source
^^^^^^^^^^^^^^^^^

The protobuf CMake package includes a number of helper functions to make the
code generation easier. In this example we are generating C++ source and use
the following code:

[source,cmake]
----
PROTOBUF_GENERATE_CPP(PROTO_SRCS PROTO_HDRS AddressBook.proto)
----

The arguments are:

  * PROTO_SRCS - Name of the variable that will store the .pb.cc files.
  * PROTO_HDRS- Name of the variable that will store the .pb.h files.
  * AddressBook.proto - The .proto file to generate code from.

[[generated-files]]
Generated Files
^^^^^^^^^^^^^^^

After the `PROTOBUF_GENERATE_CPP` function is called, you will have the above
mentioned variables available. These will be marked as the output to a custom command
which calls the protobuf compiler binary to generate them.

To then have the files generated you should add them to a library or executable.
For example:

[source,cmake]
----
add_executable(protobuf_example
    main.cpp
    ${PROTO_SRCS}
    ${PROTO_HDRS})
----

This will cause the protobuf compiler to be called when you call `make` on that
executables target.

When changes are made to the .proto file, the associated source files will be
autogenerated again. However, if no changes are made to the .proto file and you re-run
make, then nothing will be done.

[[building-the-example]]
Building the Example
{'fraction_non_alphanumeric': 0.0983274201723264, 'fraction_numerical': 0.00016894745734076703, 'mean_word_length': 4.28099910793934, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7135609', 'n_tokens_mistral': 1677, 'n_tokens_neox': 1621, 'n_words': 738}