languages.adoc

uProtocol Language Library

Table of Contents

• 1. Overview
• 2. Requirements
  • 2.1. Content
  • 2.2. Test & CI
  • 2.3. Build

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)

SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation

See the NOTICE file(s) distributed with this work for additional
information regarding copyright ownership.

This program and the accompanying materials are made available under
the terms of the Apache License Version 2.0 which is available at
https://www.apache.org/licenses/LICENSE-2.0

SPDX-FileType: DOCUMENTATION
SPDX-License-Identifier: Apache-2.0

1. Overview

uProtocol Language Libraries are written for specific programming languages like Java, C++ or Rust to provide the basic data types and functionality that is needed by uEntities like Applications and Services to interact with each other. The libraries declare the API for the uProtocol Transport and Communication Layers and provide a generic implementation of the Communication Layer API.

Class Diagram

uProtocol Transport Libraries are written for specific programming languages to provide the binding of uProtocol to concrete transport protocols like MQTT, Eclipse Zenoh or SOME/IP.

2. Requirements

2.1. Content

A language library

• MUST declare the language specific uProtocol Transport Layer interface, such that the interface can be implemented by the transport libraries.

• MUST declare the language specific uProtocol Communication Layer API, such that the interface MAY be implemented by the transport libraries.

• MUST provide a default implementation of uProtocol Communication Layer API based on the (abstract) Transport Layer API.

• MUST be named according to pattern up-[LANGUAGE], e.g. up-rust or up-python.

• MUST use the programming language specific namespace concept, if availabe, to indicate that the library belongs to the uProtocol project. If the language supports hierarchical namespaces (like Java does), then org.eclipse.uprotocol SHOULD be used. Otherwise, a namespace of uprotocol MUST be used.

• MUST contain a README file that explains how to build and use the library.

2.2. Test & CI

A language library

• SHOULD contain a test suite that covers 100% of all code and specifications defined in Content

• MUST use a CI workflow that prevents pull requests from being merged if they cannot be built.

• MUST use a CI workflow that prevents pull requests from being merged if the library’s test suite does not pass.

• MUST use a CI workflow that prevents pull requests from being merged if the library’s source code does not comply with the project’s code linting rules.

• MUST use a CI workflow that prevents pull requests from being merged if the library’s source code does not contain proper API documentation.

2.3. Build

A language library

• MUST employ an existing build system that is commonly used for the given programming language.

• MUST resolve and include external dependencies as part of the build process only.