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.
We use doxygen to generate documentation for source code. You can find the generated, versioned documentation here.
To get help with the uLib:
- File a Github Issue.
This repo is structured with two priorities:
- Separation of services/features to make it easier to find relevant information and resources.
- 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.
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.
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.
The uLib can be conveniently consumed either via CMake or other non-CMake methods (IDE workspaces, command line, and others).
-
Install the required prerequisites:
-
Clone our Azure uLib repository, optionally using the desired version tag.
git clone https://github.com/Azure/azure-ulib-c --recursive -
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).mkdir build
- Navigate to that newly created directory.
cd build - Run
cmakepointing to the sources at the root of the repo to generate the builds files.cmake ..
- Launch the underlying build system to compile the libraries.
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.
- Create an output directory for your build artifacts (in this example, we named it
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.
- az_core
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 |
For example:
-
to build uLib with samples and test
cmake .. -DUNIT_TESTING:BOOL=ON
-
to build clean uLib
cmake .. -DSKIP_SAMPLES:BOOL=ON -DPRECONDITIONS:BOOL=OFF
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.
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.
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.
Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) secure@microsoft.com. 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.
Azure uLib C is licensed under the MIT license.