Apache Avro

https://github.com/apache/avro
Admin
Apache Avro is a data serialization system that enables efficient storage and transmission of data...
Tokens:145,946
Snippets:1,191
Trust Score:9.4
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Avro from source tarball

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Getting started (Python)/_index.md

Instructions for installing from a downloaded release tarball and verifying the installation.

```shell
$ tar xvf avro-{{< avro_version >}}.tar.gz
$ cd avro-{{< avro_version >}}
$ python setup.py install
$ python
>>> import avro # should not raise ImportError
```

--------------------------------

### Compile and run the example

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Getting started (Java)/_index.md

Commands to build and execute the Java example project using Maven.

```shell
$ mvn compile
$ mvn -q exec:java -Dexec.mainClass=example.GenericMain
```

--------------------------------

### Perf benchmark example commands

Source: https://github.com/apache/avro/blob/main/lang/java/perf/README.md

Example invocations of the Perf benchmark harness: run all tests in a package, run a specific test, and run all tests with default iterations. The comments indicate the purpose of each command.

```text
-- Run all tests in a package
Perf --test org.apache.avro.perf.test.reflect.* --mi 2 --wi 2

-- Run a specific test
Perf --test org.apache.avro.perf.test.basic.IntTest --mi 3 --wi 3

-- Run all tests (measurementIterations=3, warmupIterations=3)
Perf

```

--------------------------------

### Run Hugo local server with navigateToChanged

Source: https://github.com/apache/avro/blob/main/doc/content/en/project/How to contribute/_index.md

Starts a local Hugo development server that automatically navigates to the changed file. Run from the repo root after installing a recent extended version of Hugo.

```shell
hugo server --navigateToChanged
```

--------------------------------

### Install Apache.Avro via NuGet

Source: https://github.com/apache/avro/blob/main/lang/csharp/README.md

Use this command to install the Apache.Avro package into your project.

```powershell
Install-Package Apache.Avro
```

--------------------------------

### Generic Value Implementation Usage Example

Source: https://github.com/apache/avro/blob/main/lang/c/docs/index.txt

A complete example showing how to create a generic value for a long schema, populate it in a loop, and clean up resources.

```c
avro_schema_t  schema = avro_schema_long();
avro_value_iface_t  *iface = avro_generic_class_from_schema(schema);

avro_value_t  val;
avro_generic_value_new(iface, &val);

/* Generate Avro longs from 0-499 */
int  i;
for (i = 0; i < 500; i++) {
    avro_value_reset(&val);
    avro_value_set_long(&val, i);
    /* do something with the value */
}

avro_generic_value_free(&val);
avro_value_iface_decref(iface);
avro_schema_decref(schema);
```

--------------------------------

### Require autoload.php for manual installation

Source: https://github.com/apache/avro/blob/main/lang/php/README.md

Include the autoload file in your PHP source after manual installation.

```php
<?php
require_once('avro-php/autoload.php');
```

--------------------------------

### Instance fields camelCase with underscore prefix example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for the naming rule that instance fields are camelCase and start with an underscore.

```csharp
private int _myInt;

internal string _myString;
```

--------------------------------

### Install Avro via pip

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Getting started (Python)/_index.md

The recommended way to install the Avro Python API is using pip from PyPI.

```shell
$ python3 -m pip install avro
```

--------------------------------

### Build and run the Maven example

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Getting started (Java)/_index.md

Commands to compile the project and execute the SpecificMain class.

```shell
$ mvn compile # includes code generation via Avro Maven plugin
$ mvn -q exec:java -Dexec.mainClass=example.SpecificMain
```

--------------------------------

### Manual installation commands

Source: https://github.com/apache/avro/blob/main/lang/php/README.md

Commands to extract and move the Avro PHP distribution.

```bash
tar xjf avro-php.tar.bz2 # avro-php.tar.bz2 is likely avro-php-1.4.0.tar.bz2
cp avro-php /path/to/where/you/want/it
```

--------------------------------

### dotnet_style_qualification_for_method - no this. or Me. prefix

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for dotnet_style_qualification_for_method. Shows a method invocation without this. or Me. prefix.

```csharp
Display();
```

--------------------------------

### file_header_template example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for the file_header_template option. When the template is unset or empty, no file header is required.

```csharp
namespace N2
{
    class C2 { }
}
```

--------------------------------

### Run tests with dotnet CLI

Source: https://github.com/apache/avro/blob/main/lang/csharp/README.md

Execute this command to run the project tests after installing the .NET SDK.

```bash
dotnet test
```

--------------------------------

### Constants PascalCase example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for the naming rule that constants are PascalCase.

```csharp
public const string MyConstant = "value";
```

--------------------------------

### Locals and parameters camelCase example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for the naming rule that locals and parameters are camelCase.

```csharp
private static string GetText(string path, string filename)
{
     var reader = File.OpenText($"{AppendPathSeparator(path)}{filename}");
     var text = reader.ReadToEnd();
     return text;

     string AppendPathSeparator(string filepath)
     {
        return filepath.EndsWith(@"\") ? filepath : filepath + @"\";
     }
}
```

--------------------------------

### Generated grammar productions for the example schema

Source: https://github.com/apache/avro/blob/main/lang/java/avro/src/main/java/org/apache/avro/io/parsing/doc-files/parsing.html

This block shows the production rules derived from the example schema. The terminal symbols and non-terminal identifiers (n0, r1, n1, etc.) follow the conventions described in the CFG transformation, with n0 as the start symbol.

```plaintext
  n0 ::= double n1 n2
  r1 ::= string r1 | ε
  n1 ::= arraystart r1 arrayend
  r2 ::= string n3 r2 | ε
  n2 ::= mapstart r2 mapend
  u3 ::= 1 null | 2 n4 | 3 n0
  n3 ::= union u3
  r4 ::= bytes r4 | ε
  n4 ::= arraystart r4 arrayend
```

--------------------------------

### dotnet_style_qualification_for_event - no this. or Me. prefix

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for dotnet_style_qualification_for_event. Shows an event subscription without this. or Me. prefix.

```csharp
Elapsed += Handler;
```

--------------------------------

### Preview website locally

Source: https://github.com/apache/avro/blob/main/doc/README.md

Commands to serve the website dynamically. Use the Hugo CLI directly or via Docker if Hugo is not installed.

```sh
# Serve the website dynamically using extended hugo:
hugo server --buildDrafts --buildFuture --bind 0.0.0.0 --navigateToChanged

# You can do the same thing without installing hugo via docker.
# From the Avro root directory:
docker run --rm -v $(pwd):/src -p 1313:1313 jakejarvis/hugo-extended:latest --source doc/ server \
    --buildDrafts --buildFuture --bind 0.0.0.0 --navigateToChanged
```

--------------------------------

### Grammar for an array of ints

Source: https://github.com/apache/avro/blob/main/lang/java/avro/src/main/java/org/apache/avro/io/parsing/doc-files/parsing.html

Example grammar induced by a schema that is simply an array of ints. Shows the productions for the start symbol n0 and the repeater rint.

```text
  n0 ::= arraystart rint arrayend
  rint ::= int rint | ε
```

--------------------------------

### dotnet_style_qualification_for_property - no this. or Me. prefix

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for dotnet_style_qualification_for_property. Shows a property assignment without this. or Me. prefix.

```csharp
ID = 0;
```

--------------------------------

### csharp_indent_block_contents example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows the preferred indentation for block contents. The example is a simple static method that prints "Hello".

```csharp
static void Hello()
{
    Console.WriteLine("Hello");
}
```

--------------------------------

### Build Avro Python library from source

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Getting started (Python)/_index.md

Commands to build and install the library from the root Avro directory.

```shell
$ cd lang/py/
$ python3 -m pip install -e .
$ python
```

--------------------------------

### Install avro-js with npm

Source: https://github.com/apache/avro/blob/main/lang/js/README.md

Install the avro-js package using npm. The library is compatible with node.js versions since 0.11 and major browsers via browserify.

```bash
$ npm install avro-js
```

--------------------------------

### Manual Union Type Registration Example

Source: https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/Reflect/README.md

Full example of manually registering multiple derived types within a union schema using ClassCache.

```csharp
        public class BaseClass
        {
            public string A { get; set; }
        }

        public class Derived1 : BaseClass
        {
            public int B { get; set; }
        }

        public class Derived2 : BaseClass
        {
            public double C { get; set; }
        }

        public void SerializeExample()
        {
            var baseClassSchema = @"
            [
                { ""type"" : ""record"", ""name"" : ""Dervied1"", ""fields"" :
                    [
                        { ""name"" : ""A"", ""type"" : ""string""},
                        { ""name"" : ""B"", ""type"" : ""int""}
                    ]
                },
                { ""type"" : ""record"", ""name"" : ""Dervied2"", ""fields"" :
                    [
                        { ""name"" : ""A"", ""type"" : ""string""},
                        { ""name"" : ""C"", ""type"" : ""double""}
                    ]
                },

            ]
            ";

            var schema = Schema.Parse(baseClassSchema);
            var derived1write = new Derived1() { A = "derived1", B = 7 };
            var derived2write = new Derived2() { A = "derived2", C = 3.14 };

            // union types (except for [null, type]) need to be manually registered
            var unionSchema = schema as UnionSchema;
            var cache = new ClassCache();
            cache.LoadClassCache(typeof(Derived1), unionSchema[0]);
            cache.LoadClassCache(typeof(Derived2), unionSchema[1]);
            var x = schema as RecordSchema;

            var writer = new ReflectWriter<BaseClass>(schema, cache);
            var reader = new ReflectReader<BaseClass>(schema, schema, cache);

            using (var stream = new MemoryStream(256))
            {
                var encoder = new BinaryEncoder(stream);
                writer.Write(derived1write, encoder);
                writer.Write(derived2write, encoder);
                stream.Seek(0, SeekOrigin.Begin);

                var decoder = new BinaryDecoder(stream);
                var derived1read = (Derived1)reader.Read(decoder);
                var derived2read = (Derived2)reader.Read(decoder);
            }
        }
```

--------------------------------

### dotnet_style_qualification_for_field - no this. or Me. prefix

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for dotnet_style_qualification_for_field. Shows a field assignment without this. or Me. prefix.

```csharp
capacity = 0;
```

--------------------------------

### Docker build script environment variable examples

Source: https://github.com/apache/avro/blob/main/BUILD.md

Shows how to use DOCKER_BUILD_XTRA_ARGS, DOCKER_IMAGE_NAME, and DOCKER_RUN_ENTRYPOINT to customize the Docker image build or run commands. These are alternatives for interacting with the build script.

```bash
# Rebuild the docker image without using the build cache.
DOCKER_BUILD_XTRA_ARGS=--no-cache ./build.sh docker

# Build a docker image with a specific tag (for an RC or poc, for example)
DOCKER_IMAGE_NAME=avro-build:1.10.1-rc1 ./build.sh docker

# Run a command and return.
DOCKER_RUN_ENTRYPOINT="mvn --version" ./build.sh docker
```

--------------------------------

### Basic String Datum Creation and Cleanup

Source: https://github.com/apache/avro/blob/main/lang/c/docs/index.txt

Example of creating and freeing a simple string datum using reference counting.

```c
avro_datum_t string = avro_string("This is my string");

...
avro_datum_decref(string);
```

--------------------------------

### Enable custom coders at runtime

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Getting started (Java)/_index.md

Command to run the example with the org.apache.avro.specific.use_custom_coders system property enabled for improved performance.

```shell
$ mvn -q exec:java -Dexec.mainClass=example.SpecificMain \
    -Dorg.apache.avro.specific.use_custom_coders=true
```

--------------------------------

### csharp_new_line_before_members_in_object_initializers example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows that each member in an object initializer must be placed on a new line.

```csharp
var z = new B()
{
    A = 3,
    B = 4
}
```

--------------------------------

### Example JSON output from GenerateData

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/MapReduce guide/_index.md

Sample stdout output showing JSON representations of generated Users.

```json
{"name": "user", "favorite_number": null, "favorite_color": "red"}
{"name": "user", "favorite_number": null, "favorite_color": "green"}
{"name": "user", "favorite_number": null, "favorite_color": "purple"}
{"name": "user", "favorite_number": null, "favorite_color": null}
...
```

--------------------------------

### Store and retrieve objects with datafile.cc

Source: https://github.com/apache/avro/blob/main/lang/c++/MainPage.dox

This example demonstrates the usage of Avro data files for storing and retrieving objects. Refer to DataFile.hh for additional implementation details.

```cpp
\includelineno datafile.cc
```

--------------------------------

### dotnet_style_parentheses_in_arithmetic_binary_operators example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Prefer parentheses to clarify arithmetic operator precedence. Default is always_for_clarity.

```csharp
var v = a + (b * c);
```

--------------------------------

### dotnet_style_parentheses_in_relational_binary_operators example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Prefer parentheses to clarify relational operator precedence. Default is always_for_clarity.

```csharp
var v = (a < b) == (c > d);
```

--------------------------------

### dotnet_style_parentheses_in_other_binary_operators example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Prefer parentheses to clarify other binary operator precedence. Default is always_for_clarity.

```csharp
var v = a || (b && c);
```

--------------------------------

### csharp_new_line_before_open_brace example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows the expected placement of open braces on a new line for methods and control blocks, as enforced by the csharp_new_line_before_open_brace rule.

```csharp
void MyMethod()
{
    if (...)
    {
        ...
    }
}
```

--------------------------------

### Serialize and deserialize data with Avro

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Getting started (Python)/_index.md

This example serializes two user records to a file and then reads them back. Ensure files are opened in binary mode (wb or rb) to prevent corruption.

```python
import avro.schema
from avro.datafile import DataFileReader, DataFileWriter
from avro.io import DatumReader, DatumWriter

schema = avro.schema.parse(open("user.avsc", "rb").read())

writer = DataFileWriter(open("users.avro", "wb"), DatumWriter(), schema)
writer.append({"name": "Alyssa", "favorite_number": 256})
writer.append({"name": "Ben", "favorite_number": 7, "favorite_color": "red"})
writer.close()

reader = DataFileReader(open("users.avro", "rb"), DatumReader())
for user in reader:
    print(user)
reader.close()
```

```json
{'favorite_color': None, 'favorite_number': 256, 'name': 'Alyssa'}
{'favorite_color': 'red', 'favorite_number': 7, 'name': 'Ben'}
```

--------------------------------

### csharp_space_between_method_declaration_empty_parameter_list_parentheses example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows method declarations with empty parameter lists and calls, as required by the csharp_space_between_method_declaration_empty_parameter_list_parentheses rule.

```csharp
void Goo()
{
    Goo(1);
}

void Goo(int x)
{
    Goo();
}
```

--------------------------------

### Static fields camelCase with s_ prefix example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for the naming rule that static fields are camelCase and start with s_.

```csharp
private static int s_myInt;
```

--------------------------------

### Run ColorCount MapReduce job

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/MapReduce guide/_index.md

Executes the MapredColorCount main class with input and output paths. Note that MapReduce will not start if the output folder already exists.

```shell
mvn exec:java -q -Dexec.mainClass=example.MapredColorCount -Dexec.args="input output"
```

--------------------------------

### csharp_using_directive_placement - using directives outside namespace

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for csharp_using_directive_placement. Shows using directives placed outside the namespace.

```csharp
using System;

namespace Conventions
{

}
```

--------------------------------

### Implementing ArrayHelper for ConcurrentQueue and using it with ReflectWriter/Reader

Source: https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/Reflect/README.md

Provides a complete example of a custom ArrayHelper for ConcurrentQueue, including the required schema with 'helper' metadata, and demonstrates how to register the helper in a ClassCache and use it with ReflectWriter and ReflectReader.

```csharp

    public class ConcurrentQueueHelper<T> : ArrayHelper
    {
        public override int Count()
        {
            ConcurrentQueue<T> e = (ConcurrentQueue<T>)Enumerable;
            return e.Count;
        }

        public override void Add(object o)
        {
            ConcurrentQueue<T> e = (ConcurrentQueue<T>)Enumerable;
            e.Enqueue((T)o);
        }

        public override void Clear()
        {
            ConcurrentQueue<T> e = (ConcurrentQueue<T>)Enumerable;
#if NET461
            while (e.TryDequeue(out _)) { }
#else
            e.Clear();
#endif
        }

        public override Type ArrayType
        {
            get => typeof(ConcurrentQueue<>);
        }

        public ConcurrentQueueHelper(IEnumerable enumerable) : base(enumerable)
        {
            Enumerable = enumerable;
        }
    }

    string recordList = @"
    {
        ""type"": ""array"",
        ""helper"": ""recordListQueue"",
        ""items"": ""string""
    }"

    // using the helper

    var schema = Schema.Parse(recordList);
    var fixedRecWrite = new ConcurrentQueue<string>();

    var cache = new ClassCache();
    cache.AddArrayHelper("recordListQueue", typeof(ConcurrentQueueHelper<string>));

    var writer = new ReflectWriter<ConcurrentQueue<ConcurrentQueueRec>>(schema, cache);
    var reader = new ReflectReader<ConcurrentQueue<ConcurrentQueueRec>>(schema, schema, cache);
```

--------------------------------

### Fullname Resolution Example

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Specification/_index.md

A JSON schema demonstrating how fullnames are resolved through inheritance and explicit namespace attributes.

```json
{
  "type": "record",
  "name": "Example",
  "doc": "A simple name (attribute) and no namespace attribute: use the null namespace (\""); the fullname is 'Example'.",
  "fields": [
    {
      "name": "inheritNull",
      "type": {
        "type": "enum",
        "name": "Simple",
        "doc": "A simple name (attribute) and no namespace attribute: inherit the null namespace of the enclosing type 'Example'. The fullname is 'Simple'.",
        "symbols": ["a", "b"]
      }
    }, {
      "name": "explicitNamespace",
      "type": {
        "type": "fixed",
        "name": "Simple",
        "namespace": "explicit",
        "doc": "A simple name (attribute) and a namespace (attribute); the fullname is 'explicit.Simple' (this is a different type than of the 'inheritNull' field).",
        "size": 12
      }
    }, {
      "name": "fullName",
      "type": {
        "type": "record",
        "name": "a.full.Name",
        "namespace": "ignored",
        "doc": "A name attribute with a fullname, so the namespace attribute is ignored. The fullname is 'a.full.Name', and the namespace is 'a.full'.",
        "fields": [
          {
            "name": "inheritNamespace",
            "type": {
              "type": "enum",
              "name": "Understanding",
              "doc": "A simple name (attribute) and no namespace attribute: inherit the namespace of the enclosing type 'a.full.Name'. The fullname is 'a.full.Understanding'.",
              "symbols": ["d", "e"]
            }
          }
        ]
      }
    }
  ]
}
```

--------------------------------

### Configure Documentation Build Process

Source: https://github.com/apache/avro/blob/main/lang/c/docs/CMakeLists.txt

Iterates through source files to create custom commands and targets for HTML generation if the required tools are found.

```cmake
if (ASCIIDOC_EXECUTABLE AND SOURCE_HIGHLIGHT_EXECUTABLE)
    foreach(_file ${AVRO_DOC_SRC})
        get_filename_component(_file_we ${_file} NAME_WE)
        set(_file_path "${CMAKE_CURRENT_SOURCE_DIR}/${_file}")
        set(_html_out "${CMAKE_CURRENT_BINARY_DIR}/${_file_we}.html")
        add_custom_command(
            OUTPUT "${_html_out}"
            COMMAND ${ASCIIDOC_EXECUTABLE}
                -a avro_version=${AVRO_VERSION}
                -a libavro_version=${LIBAVRO_VERSION}
                -a toc
                --unsafe -n -o "${_html_out}" "${_file_path}"
            DEPENDS "${_file_path}"
            COMMENT "asciidoc ${_file}"
        )
        install(FILES "${_html_out}" DESTINATION share/doc/avro-c)
        add_custom_target("${_file_we}_html" ALL echo -n
            DEPENDS "${_file}" "${_html_out}"
        )
        add_custom_target(docs DEPENDS "${_html_out}")
    endforeach(_file)
else(ASCIIDOC_EXECUTABLE AND SOURCE_HIGHLIGHT_EXECUTABLE)
    message(WARNING "asciidoc and/or source-highlight not found. HTML documentation will *NOT* be built.")
endif(ASCIIDOC_EXECUTABLE AND SOURCE_HIGHLIGHT_EXECUTABLE)
```

--------------------------------

### csharp_space_after_dot example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows a method call with no space before the dot, as required by the csharp_space_after_dot rule.

```csharp
this.Goo();
```

--------------------------------

### csharp_new_line_between_query_expression_clauses example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows that each clause in a query expression must be placed on a new line.

```csharp
var q = from a in e
        from b in e
        select a * b;
```

--------------------------------

### Get length of bytes value using NULL dest

Source: https://github.com/apache/avro/blob/main/lang/c/docs/index.txt

Example showing how to retrieve only the length of a bytes value by passing NULL for the dest parameter. The size parameter receives the length.

```c
avro_value_t  *value = /* from somewhere */;
size_t  size;
avro_value_get_bytes(value, NULL, &size);
```

--------------------------------

### JSON encoding and decoding with Type

Source: https://github.com/apache/avro/blob/main/lang/js/doc/Home.md

Shows how to convert a value to its JSON representation and back using toString and fromString. The example uses the string 'Hi' and demonstrates round-tripping.

```javascript
var jsonString = type.toString('Hi'); // === '"Hi"'
var str = type.fromString(jsonString); // === 'Hi'
```

--------------------------------

### csharp_style_namespace_declarations - block_scoped vs file_scoped

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for csharp_style_namespace_declarations. Shows both block_scoped and file_scoped namespace declaration styles.

```csharp
// csharp_style_namespace_declarations = block_scoped
using System;

namespace Convention
{
    class C
    {
    }
}

// csharp_style_namespace_declarations = file_scoped
using System;

namespace Convention;
class C
{
}
```

--------------------------------

### Define setup_avro_lib function

Source: https://github.com/apache/avro/blob/main/lang/c++/CMakeLists.txt

Creates a function that adds a library target from AVRO_SOURCE_FILES, sets compile definitions (AVRO_SOURCE, and AVRO_DYN_LINK for shared), sets the version, links ZLIB, Snappy, and Zstd, and sets public include directories for build and install.

```cmake
function (setup_avro_lib target lib_type)
    add_library (${target} ${lib_type} ${AVRO_SOURCE_FILES})
    target_compile_definitions (${target} PRIVATE AVRO_SOURCE)
    if (lib_type STREQUAL SHARED)
        target_compile_definitions (${target} PUBLIC AVRO_DYN_LINK)
    endif ()
    set_target_properties (${target} PROPERTIES VERSION ${AVRO_VERSION})
    target_link_libraries (${target} PUBLIC
      $<BUILD_INTERFACE:ZLIB::ZLIB>
      $<BUILD_INTERFACE:$<TARGET_NAME_IF_EXISTS:Snappy::snappy>>
      $<$<BOOL:${zstd_FOUND}>:$<BUILD_INTERFACE:$<TARGET_NAME_IF_EXISTS:${ZSTD_TARGET}>>>
      $<INSTALL_INTERFACE:ZLIB::ZLIB>
      $<INSTALL_INTERFACE:$<TARGET_NAME_IF_EXISTS:Snappy::snappy>>
      $<$<BOOL:${zstd_FOUND}>:$<INSTALL_INTERFACE:$<TARGET_NAME_IF_EXISTS:${ZSTD_TARGET}>>>
    )
    target_include_directories (${target} PUBLIC
      $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
      $<INSTALL_INTERFACE:include>
    )
endfunction (setup_avro_lib)
```

--------------------------------

### Patch creation guidelines - do

Source: https://github.com/apache/avro/blob/main/doc/content/en/project/How to contribute/_index.md

Recommended practices when creating a patch, including adhering to coding style and updating documentation.

```text
try to adhere to the coding style of files you edit;
comment code whose function or rationale is not obvious;
update documentation (e.g., package.html files, this wiki, etc.)
name the patch file after the JIRA – AVRO-<JIRA#>.patch
```

--------------------------------

### Record binary encoding example

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Specification/_index.md

Hex byte sequence for a record instance with a=27 and b="foo", showing concatenation of field encodings.

```text
36 06 66 6f 6f
```

--------------------------------

### Add subdirectories and pretty target

Source: https://github.com/apache/avro/blob/main/lang/c/CMakeLists.txt

Adds source, examples, tests, and docs subdirectories, and defines a custom target 'pretty' that runs a CMake script for formatting.

```cmake
add_subdirectory(src)
add_subdirectory(examples)
add_subdirectory(tests)
add_subdirectory(docs)

add_custom_target(pretty
    "${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_SOURCE_DIR}/cmake_pretty.cmake")
```

--------------------------------

### Perf command-line usage

Source: https://github.com/apache/avro/blob/main/lang/java/perf/README.md

Shows the command-line usage for the Perf benchmark harness, listing the available options: --help, --mi for measurement iterations, --test for the test to run, and --wi for warmup iterations.

```text
usage: Perf [--help] [--mi <measurementIterations>] [--test <test>] [--wi <warmupIterations>]

```

--------------------------------

### Array binary encoding example

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Specification/_index.md

Hex byte sequence for an array containing items 3 and 27, showing count, items, and terminating zero.

```text
04 06 36 00
```

--------------------------------

### Create and use a ClassCache

Source: https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/Reflect/README.md

Demonstrates initializing a ClassCache to minimize reflection overhead and passing it to ReflectWriter and ReflectReader.

```csharp
    var cache = new ClassCache();
    var writer = new ReflectWriter<MultiList>(schema, cache);
    var reader = new ReflectReader<MultiList>(schema, schema, cache);
```

--------------------------------

### Non-private static fields PascalCase example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for the naming rule that non-private static fields are PascalCase.

```csharp
public static MyString = "value";
protected static MyString = "value";
internal static MyString = "value";
protected_internal static MyString = "value";
private_protected static MyString = "value";;
```

--------------------------------

### Find Documentation Tools

Source: https://github.com/apache/avro/blob/main/lang/c/docs/CMakeLists.txt

Locates the required asciidoc and source-highlight executables on the system.

```cmake
message(STATUS "Searching for asciidoc...")
find_program(ASCIIDOC_EXECUTABLE asciidoc)
find_program(SOURCE_HIGHLIGHT_EXECUTABLE source-highlight)
```

--------------------------------

### Initialize Hugo submodules

Source: https://github.com/apache/avro/blob/main/doc/README.md

Run this command before building the website to ensure all submodules are initialized.

```sh
hugo mod get -u
```

--------------------------------

### csharp_indent_labels example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows that labels are placed at one less indent than the current context. The example uses a goto error label inside a method.

```csharp
class C
{
    private string MyMethod(...)
    {
        if (...) {
            goto error;
        }
    error:
        throw new Exception(...);
    }
}
```

--------------------------------

### Struct definition for Win32 initialization example

Source: https://github.com/apache/avro/blob/main/lang/c/README.maintaining_win32.txt

Defines a struct test_t with two integer fields, used to illustrate Win32 struct initialization restrictions.

```c
typedef struct
{
   int a;
   int b;
} test_t;
```

--------------------------------

### csharp_indent_case_contents example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows the preferred indentation for case contents inside a switch statement. The example uses a switch on Color.Red and Color.Blue with default case.

```csharp
switch(c) {
    case Color.Red:
        Console.WriteLine("The color is red");
        break;
    case Color.Blue:
        Console.WriteLine("The color is blue");
        break;
    default:
        Console.WriteLine("The color is unknown.");
        break;
}
```

--------------------------------

### Create new release blog entry

Source: https://github.com/apache/avro/blob/main/doc/README.md

Copy an existing release markdown file to create a new entry for the blog section.

```sh
cp content/en/blog/releases/avro-1.12.0-released.md content/en/blog/releases/avro-1.13.0-released.md
```

--------------------------------

### csharp_indent_case_contents_when_block example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows the preferred indentation for case contents when the case body is a block. The example uses a case 0 with a block containing a Console.WriteLine and a break.

```csharp
case 0:
    {
        Console.WriteLine("Hello");
        break;
    }
```

--------------------------------

### Upload API documentation to SVN

Source: https://github.com/apache/avro/blob/main/doc/README.md

Commands to checkout the SVN site repository, create the version directory, copy API files, and commit the changes.

```sh
svn co https://svn.apache.org/repos/asf/avro/site
cd site/publish/docs/
mkdir 1.12.0
cd 1.12.0
mkdir api
cp -r ~/Desktop/avro-release-dist/avro-1.12.0/avro-doc-1.12.0/api/ api/
svn commit -m "Avro 1.12.0 release"
```

--------------------------------

### record.$getType()

Source: https://github.com/apache/avro/blob/main/lang/js/doc/API.md

Get the record's type.

```APIDOC
## record.$getType()

### Description
Get the record's type.

### Method
$getType

### Endpoint
record.$getType()

### Parameters
No parameters.
```

--------------------------------

### Sample schema and invalid record for errorHook examples

Source: https://github.com/apache/avro/blob/main/lang/js/doc/API.md

Defines a sample Avro record schema for a Person with an age field and an array of names, and a corresponding invalid record with a null age and a non-string name. Used as the basis for the subsequent errorHook examples.

```javascript
// A sample schema.
var personType = avro.parse({
  type: 'record',
  name: 'Person',
  fields: [
    {name: 'age', type: 'int'},
    {name: 'names', type: {type: 'array', items: 'string'}}
  ]
});

// A corresponding invalid record.
var invalidPerson = {age: null, names: ['ann', 3, 'bob']};
```

--------------------------------

### Verify PGP signatures with GPG

Source: https://github.com/apache/avro/blob/main/doc/content/en/project/Download/_index.md

Import the KEYS file and verify the downloaded file's signature using GPG. Ensure you download the KEYS and .asc files from the main distribution directory, not a mirror.

```shell
% gpg --import KEYS
% gpg --verify downloaded_file.asc downloaded_file
```

--------------------------------

### Implement recursive schemata with explicit type specification

Source: https://github.com/apache/avro/blob/main/lang/js/README.md

Parse a recursive record type (a linked list) and demonstrate that nested recursive types must be explicitly specified. The valid example uses a 'LongList' wrapper for the nested object, while the invalid example omits it and will throw an error.

```javascript
  // example type: linked list with one long-int as element value
  const recursiveRecordType =  avro.parse({
    "type": "record",
    "name": "LongList",
    "fields" : [
      {"name": "value", "type": "long"},             
      {"name": "next", "type": ["null", "LongList"]} // optional next element via recursion
    ]
  });

  // will work
  const validRecursiveRecordDTO = {
    value: 1,
    next: {
      // no duck-typing support: from first nested level on the 
      // recursive type has to be explicitly specified.
      LongList: {
        value: 2,
        next: null
      }
    }
  };
  const serializedValid = recursiveRecordType.parse(validRecursiveRecordDTO);
  

  // will throw error
  const invalidRecursiveRecordDTO = {
    value: 1,
    next: {
        value: 2,
        next: null
    }
  };
  const serializedInvalid = recursiveRecordType.parse(invalidRecursiveRecordDTO);
```

--------------------------------

### Binary Encoding of String "foo"

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Specification/_index.md

Example showing the binary encoding of the three-character string "foo", represented as the long value 3 followed by the UTF-8 bytes for 'f', 'o', and 'o'.

```text
06 66 6f 6f
```

--------------------------------

### Generate static HTML with hugo

Source: https://github.com/apache/avro/blob/main/doc/content/en/project/How to contribute/_index.md

Generates the static HTML files into the public/ folder. Run after stopping the Hugo server with Ctrl+C. The generated HTML is what gets deployed.

```shell
hugo
```

--------------------------------

### BlockDecoder.getDefaultCodecs()

Source: https://github.com/apache/avro/blob/main/lang/js/doc/API.md

Get built-in decompression functions (currently null and deflate).

```APIDOC
## BlockDecoder.getDefaultCodecs()

### Description
Get built-in decompression functions (currently null and deflate).

### Method
getDefaultCodecs

### Endpoint
BlockDecoder.getDefaultCodecs()

### Parameters
No parameters.
```

--------------------------------

### Record.getType()

Source: https://github.com/apache/avro/blob/main/lang/js/doc/API.md

Convenience class method to get the record's type.

```APIDOC
## Record.getType()

### Description
Convenience class method to get the record's type.

### Method
getType

### Endpoint
Record.getType()

### Parameters
No parameters.
```

--------------------------------

### Compile the Maven project

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/MapReduce guide/_index.md

Builds the project, including code generation for the User schema.

```shell
mvn compile
```

--------------------------------

### Union string encoding example

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Specification/_index.md

Hex byte sequence for encoding the string "a" in the union schema ["null","string"], showing index and serialized string.

```text
02 02 61
```

--------------------------------

### build.sh usage for test, dist, clean

Source: https://github.com/apache/avro/blob/main/BUILD.md

Lists the primary build.sh commands: test runs tests for all languages, dist creates release distribution files in dist/, and clean removes generated artifacts.

```bash
./build.sh test # runs tests for all languages
./build.sh dist # creates all release distribution files in dist/
./build.sh clean # removes all generated artifacts
```

--------------------------------

### dotnet_style_parentheses_in_other_operators example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Prefer to not have parentheses when operator precedence is obvious. Default is never_if_unnecessary.

```csharp
var v = a.b.Length;
```

--------------------------------

### Unsupported designated initializer on Win32

Source: https://github.com/apache/avro/blob/main/lang/c/README.maintaining_win32.txt

Shows the designated initializer syntax that is not supported on Win32.

```c
test_t t2 = { .a = 0, . b = 0 };
```

--------------------------------

### Initialize DataFileWriter

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Getting started (Python)/_index.md

Creates a DataFileWriter to serialize items to disk using a specified schema and DatumWriter.

```python
writer = DataFileWriter(open("users.avro", "wb"), DatumWriter(), schema)
```

--------------------------------

### Create a server listener for transient streams (Express)

Source: https://github.com/apache/avro/blob/main/lang/js/doc/Advanced-usage.md

Sets up an Express server that listens on port 3000 and handles POST requests by creating a protocol listener that uses the response object for communication.

```javascript
var app = require('express')();

app.post('/', function (req, res) {
  protocol.createListener(function (cb) { cb(res); return req; });
});

app.listen(3000);
```

--------------------------------

### csharp_space_after_semicolon_in_for_statement example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows a for loop with spaces after semicolons, as required by the csharp_space_after_semicolon_in_for_statement rule.

```csharp
for (int i = 0; i < x.Length; i++)
```

--------------------------------

### csharp_space_after_keywords_in_control_flow_statements example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows a for loop with a space after the for keyword, as required by the csharp_space_after_keywords_in_control_flow_statements rule.

```csharp
for (int i;i<x;i++) { ... }
```

--------------------------------

### Initialize DataFileReader

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Getting started (Python)/_index.md

Opens an Avro file for reading using a DataFileReader and DatumReader.

```python
reader = DataFileReader(open("users.avro", "rb"), DatumReader())
```

--------------------------------

### Load Avro schema from file with avro.parse

Source: https://github.com/apache/avro/blob/main/lang/js/doc/Home.md

Shows how to load a JSON-serialized Avro schema from a file by passing a path to avro.parse.

```javascript
var couponType = avro.parse('./Coupon.avsc');
```

--------------------------------

### Perform basic serialization with ReflectWriter

Source: https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/Reflect/README.md

Demonstrates how to use ReflectWriter to serialize a C# object into a binary stream based on a provided schema.

```csharp
    Schema schema; // created previously
    T myObject; // created previously


    var avroWriter = new ReflectWriter<T>(schema);
    using (var stream = new MemoryStream(256))
    {
        avroWriter.Write(myObject, new BinaryEncoder(stream));
    }
```

--------------------------------

### Build the Docker image

Source: https://github.com/apache/avro/blob/main/doc/content/en/project/How to contribute/_index.md

Builds the avro-website Docker image. Requires Docker Desktop on Windows/Mac or Docker Compose on Linux.

```shell
docker-compose build
```

--------------------------------

### csharp_space_after_comma example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows an array initializer with spaces after commas, as required by the csharp_space_after_comma rule.

```csharp
int[] x = new int[] { 1 , 2 , 3 , 4 , 5 };
```

--------------------------------

### csharp_space_after_cast example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows a cast expression with a space after the cast, as required by the csharp_space_after_cast rule.

```csharp
int y = (int)x;
```

--------------------------------

### Copy C API documentation to external folder

Source: https://github.com/apache/avro/blob/main/doc/content/en/project/How to contribute/_index.md

Copies the built C API HTML documentation to the external folder for the website.

```shell
cp ../avro/build/avro-doc-1.12.0-SNAPSHOT/api/c/* content/en/docs/external/c/
```

--------------------------------

### dotnet_code_quality_unused_parameters

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for the dotnet_code_quality_unused_parameters rule, which flags methods with any accessibility that contain unused parameters. The default is all.

```csharp
public int GetNum1(int unusedParam) { return 1; }
internal int GetNum2(int unusedParam) { return 1; }
private int GetNum3(int unusedParam) { return 1; }
```

--------------------------------

### csharp_style_unused_value_expression_statement_preference

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for the csharp_style_unused_value_expression_statement_preference rule, which prefers assigning an unused expression to a discard. The default is discard_variable.

```csharp
_ = System.Convert.ToInt32("35");
```

--------------------------------

### Perform basic deserialization with ReflectReader

Source: https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/Reflect/README.md

Demonstrates how to use ReflectReader to deserialize binary data back into a C# object using a schema.

```csharp
    Schema schema; // created previously

    // using same writer and reader schema in this example.
    var avroReader = new ReflectReader<T>(schema, schema);

    using (var stream = new MemoryStream(serialized))
    {
        deserialized = avroReader.Read(null, new BinaryDecoder(stream));
    }
```

--------------------------------

### csharp_new_line_before_members_in_anonymous_types example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows that each member in an anonymous type initializer must be placed on a new line.

```csharp
var z = new
{
    A = 3,
    B = 4
}
```

--------------------------------

### Union Value Methods

Source: https://github.com/apache/avro/blob/main/lang/c/docs/index.txt

Functions to get the current branch of a union and to set the active branch.

```APIDOC
## Union Value Methods

### Description
These functions operate on Avro union values. They allow you to query the current branch and to set the active branch.

### Functions

#### avro_value_get_discriminant

- **Signature**: `int avro_value_get_discriminant(const avro_value_t *union_val, int *disc);`
- **Description**: Returns the current discriminant (branch index) of the union value without modifying the selected branch.
- **Parameters**:
  - `union_val` (const avro_value_t *) - The union value.
  - `disc` (int *) - Output parameter to receive the discriminant.
- **Returns**: int - Status code (0 on success).

#### avro_value_get_current_branch

- **Signature**: `int avro_value_get_current_branch(const avro_value_t *union_val, avro_value_t *branch);`
- **Description**: Returns the current branch value of the union without modifying the selected branch.
- **Parameters**:
  - `union_val` (const avro_value_t *) - The union value.
  - `branch` (avro_value_t *) - Output parameter to receive the branch value.
- **Returns**: int - Status code (0 on success).

#### avro_value_set_branch

- **Signature**: `int avro_value_set_branch(avro_value_t *union_val, int discriminant, avro_value_t *branch);`
- **Description**: Sets the active branch of the union to the given discriminant and fills in `branch` to point at the branch's value instance. Most implementations detect if the desired branch is already selected, so it is safe to call this method always.
- **Parameters**:
  - `union_val` (avro_value_t *) - The union value.
  - `discriminant` (int) - The discriminant (branch index) to select.
  - `branch` (avro_value_t *) - Output parameter to receive the branch value.
- **Returns**: int - Status code (0 on success).

```

--------------------------------

### String Datum Creation Methods

Source: https://github.com/apache/avro/blob/main/lang/c/docs/index.txt

Three methods for creating string datums with different memory management strategies.

```c
avro_datum_t avro_string(const char *str);
avro_datum_t avro_wrapstring(const char *str);
avro_datum_t avro_givestring(const char *str);
```

--------------------------------

### Build Avro-cpp.sln with MSBuild

Source: https://github.com/apache/avro/blob/main/lang/c++/MSBUILD.md

After CMake configuration, run this MSBuild command to build the solution in Release configuration for x64 platform.

```msbuild
msbuild Avro-cpp.sln /p:Configuration=Release /p:Platform=x64
```

--------------------------------

### csharp_space_around_binary_operators example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows a return expression with spaces around the binary operators, as required by the csharp_space_around_binary_operators rule.

```csharp
return x * (x - y);
```

--------------------------------

### csharp_space_before_colon_in_inheritance_clause example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows an interface and a class with a space before the colon in the inheritance clause, as required by the csharp_space_before_colon_in_inheritance_clause rule.

```csharp
interface I
{

}

class C : I
{

}
```

--------------------------------

### Build inside Docker container

Source: https://github.com/apache/avro/blob/main/BUILD.md

Starts a Docker container with all build requirements and runs the Avro build script. The first build may take 20+ minutes to download dependencies; subsequent runs use a cached image. The working directory is mounted from the host.

```bash
./build.sh docker
docker@539f6535c9db:~/avro$ cd lang/java/
docker@539f6535c9db:~/avro/lang/java$ ./build.sh test
[INFO] Scanning for projects...
```

--------------------------------

### List output directory contents

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/MapReduce guide/_index.md

Shows the expected output files after ColorCount completes.

```shell
$ ls output/
part-00000.avro  _SUCCESS
```

--------------------------------

### csharp_new_line_before_else example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows that the else keyword must be placed on a new line after the closing brace of the if block.

```csharp
if (...) {
    ...
}
else {
    ...
}
```

--------------------------------

### Array schema example

Source: https://github.com/apache/avro/blob/main/doc/content/en/docs/++version++/Specification/_index.md

JSON schema for an array of long items. Used to illustrate block-based encoding.

```json
{"type": "array", "items": "long"}
```

--------------------------------

### Run unit tests for each language implementation

Source: https://github.com/apache/avro/blob/main/doc/content/en/project/How to contribute/_index.md

Commands to build and run unit tests for Avro's language modules. Each block handles a different language.

```shell
cd avro-trunk/lang/java
mvn clean test

```

```shell
cd avro-trunk/lang/py
./setup.py build test

```

```shell
cd avro-trunk/lang/rust
./build.sh clean test

```

```shell
cd avro-trunk/lang/csharp
./build.sh clean test

```

```shell
cd avro-trunk/lang/c
./build.sh clean
./build.sh test

```

```shell
cd avro-trunk/lang/c++
./build.sh clean test

```

```shell
cd avro-trunk/lang/ruby
gem install echoe
rake clean test

```

```shell
cd avro-trunk/lang/php
./build.sh clean
./build.sh test

```

--------------------------------

### Calculate hash with certUtil on Windows

Source: https://github.com/apache/avro/blob/main/doc/content/en/project/Download/_index.md

Use certUtil on Windows 7 and later to calculate a file hash. Choose from hash algorithms: MD2, MD4, MD5, SHA1, SHA256, SHA384, SHA512.

```shell
% certUtil -hashfile pathToFileToCheck
```

--------------------------------

### csharp_style_unused_value_assignment_preference

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Example for the csharp_style_unused_value_assignment_preference rule, which prefers using a discard when assigning a value that's not used. The default is discard_variable.

```csharp
int GetCount(Dictionary<string, int> wordCount, string searchWord)
{
    _ = wordCount.TryGetValue(searchWord, out var count);
    return count;
}
```

--------------------------------

### Run the built Docker image

Source: https://github.com/apache/avro/blob/main/doc/content/en/project/How to contribute/_index.md

Runs the avro-website container with a volume bound to the avro-website folder. Can be combined with the build command using docker-compose up --build.

```shell
docker-compose up
```

--------------------------------

### csharp_space_between_method_call_parameter_list_parentheses example

Source: https://github.com/apache/avro/blob/main/lang/csharp/STYLING.md

Shows a method call with no spaces inside the parameter list parentheses, as required by the csharp_space_between_method_call_parameter_list_parentheses rule.

```csharp
MyMethod(argument);
```
Tokens:
Raw