Azure uLib C - PREVIEW

THIS REPO IS CURRENTLY IN PREVIEW. THE API'S ARE NOT FINAL AND ARE SUBJECT TO CHANGE WITHOUT NOTICE.

The intention of this repository is to provide developers useful tools to make developing for small, limited-resource devices easier.

This repository contains the following:

• uStream: avoid copying memory and expose large amounts of data without using a large amount of memory. Samples can be found here.

Table of Contents

• Azure uLib C
  • Table of Contents
  • Documentation
  • The GitHub Repository
    • Structure
    • Master Branch
    • Release Branches and Release Tagging
  • Getting Started Using the uLib
    • CMake
    • CMake Options
    • Development Environment
  • Creating Your Own uStream
  • Contributing
    • Reporting Security Issues and Security Bugs
    • License

Documentation

We use doxygen to generate documentation for source code. You can find the generated, versioned documentation here.

The GitHub Repository

To get help with the uLib:

• File a Github Issue.

Structure

This repo is structured with two priorities:

1. Separation of services/features to make it easier to find relevant information and resources.
2. Simplified source file structuring to easily integrate features into a user's project.

    /docs - documentation for each service (iot, etc)
    /inc - include directory - can be singularly included in your project to resolve all headers
    /samples - samples for each service
    /src - source files for each service
    /tests - tests for each service

For instructions on how to consume the libraries via CMake, please see here. For instructions on how consume the source code in an IDE, command line, or other build systems, please see here.

Master Branch

The master branch has the most recent code with new features and bug fixes. This repo is under construction, so it does not represent the General Availability (GA) release of the uLib.

Release Branches and Release Tagging

When we make an official release, we will create a unique git tag containing the name and version to mark the commit. We'll use this tag for servicing via hotfix branches as well as debugging the code for a particular beta or stable release version.

Getting Started Using the uLib

The uLib can be conveniently consumed either via CMake or other non-CMake methods (IDE workspaces, command line, and others).

CMake

1. Install the required prerequisites:
   • CMake version 3.10 or later
   • C compiler: MSVC, gcc or clang are recommended
   • git to clone our Azure uLib repository with the desired tag
2. Clone our Azure uLib repository, optionally using the desired version tag.

    git clone https://github.com/Azure/azure-ulib-c --recursive
   

3. Ensure the uLib builds correctly.
   • Create an output directory for your build artifacts (in this example, we named it build, but you can pick any name). ```bash mkdir build ```
   • Navigate to that newly created directory. ```bash cd build ``
   • Runcmakepointing to the sources at the root of the repo to generate the builds files. ``bash cmake .. ```
   • Launch the underlying build system to compile the libraries. ```bash cmake –build . ``` This results in building uLib as a static library file, placed in the output directory you created. It creates a few samples in that you can directly run from the samples directory.

CMake Options

By default, when building the project with no options, the following static libraries are generated:

• Libraries:
  • az_core
    • az_span, az_http, az_json, etc.
  • azure_ulib_c
    • az_ustream, az_ipc, etc.

The following CMake options are available for adding/removing project features.

Option	Description	Default Value
UNIT_TESTING	Generates Unit Test for compilation. When turning this option ON, cmocka is a required dependency for compilation. After Compiling, use ctest to run Unit Test.	OFF
PRECONDITIONS	Turning this option OFF would remove all method contracts. This is typically for shipping libraries for production to make it as optimized as possible.	ON
LOGGING	Build uLib with logging support using Azure Core Library's AZ_LOG.	ON
SKIP_SAMPLES	When turning ON, the compiler will not build the samples.	OFF

example:

• to build uLib with samples and test

  ```bash cmake .. -DUNIT_TESTING:BOOL=ON ```

• to build clean uLib

  ```bash cmake .. -DSKIP_SAMPLES:BOOL=ON -DPRECONDITIONS:BOOL=OFF ```

Development Environment

Project contains files to work on Windows, Mac or Linux based OS.

Note For any environment variables set to use with CMake, the environment variables must be set BEFORE the first cmake generation command (cmake ..). The environment variables will NOT be picked up if you have already generated the build files, set environment variables, and then regenerate. In that case, you must either delete the CMakeCache.txt file or delete the folder in which you are generating build files and start again.

Creating Your Own uStream

Using the specification listed here in the documentation, you can create your own implementation of a ustream. In order to ensure that it behaves according to the specification, we have created tests which you can run against your implementation. You can use ustream_ut_sample.c and ustream_e2e_sample.c in tests_sample as a reference. TODO's have been placed in the sample files to help guide what you need to implement.

Contributing

For details on contributing to this repository, see the contributing guide.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Reporting Security Issues and Security Bugs

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) secur.nosp@m.e@mi.nosp@m.croso.nosp@m.ft.c.nosp@m.om. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

License

Azure uLib C is licensed under the MIT license.