Merge branch 'develop' into stable

.clang-format

@@ -24,7 +24,8 @@ BraceWrapping:
 # Misc other options
 AccessModifierOffset: -2
 AlignAfterOpenBracket: Align
-AlignConsecutiveDeclarations: false
+AlignConsecutiveDeclarations: true
+BinPackParameters: false
 AlignOperands: true
 AllowAllParametersOfDeclarationOnNextLine: false
 AllowShortBlocksOnASingleLine: false
@@ -35,7 +36,7 @@ AllowShortLoopsOnASingleLine: false
 BreakConstructorInitializers: BeforeComma
 ColumnLimit: 120
 DerivePointerAlignment: false
-PointerAlignment: Right
+PointerAlignment: Left
 SortIncludes: false
 
 # Leave Doxygen directives alone

.editorconfig

@@ -0,0 +1,24 @@
+# EditorConfig file for ETC R&D Network Products dept.
+#
+# To learn more about EditorConfig, go to https://editorconfig.org
+#
+# To enforce the settings in this file, you may need to download a plugin for
+# your editor of choice: https://editorconfig.org/#download
+#
+# Currently covers C, C++ and Python
+# Revision 1: 2019-07-01
+
+# This is the top-level EditorConfig file for this project.
+root = true
+
+# Settings to apply to every file affected by this EditorConfig
+# Sections lower than this override this section.
+[*.{c,cpp,cxx,c++,cc,h,hh,hpp,inl,ipp,py}]
+indent_style = space            # Indent using spaces
+indent_size = 2                 # Each indentation level is 2 spaces
+trim_trailing_whitespace = true # Trim trailing whitespace from each line
+insert_final_newline = true     # Add a final newline to each file if missing
+
+# Specific overrides for Python only
+[*.py]
+indent_size = 4                 # For Python, use 4 space indentation per PEP-8

.gitignore

@@ -13,7 +13,7 @@ lib/
 #######################
 
 # CMake
-build/
+build*/
 
 # MSVC2015 and Qt
 *.VC.db

CHANGELOG.md

@@ -1,10 +1,55 @@
 # Changelog
-All notable changes to the lwpa library will be documented in this file.
+All notable changes to the EtcPal library will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2020-08-18
+
+Note: This is a pre-release version. This version changelog is not exhaustive.
+
+### Added
+- New port: Linux
+- New port: macOS
+- New port: iOS
+- New port: FreeRTOS
+- New port: lwIP
+- etcpal_init() in etcpal/common.h. etcpal_init() must be called before using
+  features defined by feature macros defined in etcpal/common.h.
+- Extra documentation page for network interface indexes.
+- Addition of a C++ wrapper layer over EtcPal. Added wrapper classes for error,
+  inet, lock, log, queue, thread, timer and uuid.
+- New module etcpal/queue for RTOS queues. FreeRTOS only for now.
+- etcpal/lock: A counting semaphore API.
+- etcpal/lock: Functions for posting signals and semaphores from an interrupt
+  context.
+- etcpal/uuid: Functions to generate version 3 and version 5 UUIDs.
+- etcpal/log: Legacy syslog creation added. Interface changed slightly to
+  support this.
+
+### Changed
+- Naming: Library name changed from lwpa to EtcPal. All API names updated
+  accordingly.
+- Naming: Separated the platform-specific sources into 'os' and 'net' targets
+  to aid in targeting mix-and-match stack environments like FreeRTOS and lwIP.
+- Allow EtcPal to be built with no networking support.
+- Improvements in mnemonic consistency across the public APIs, including
+  addition of meaningful return information, better function naming, etc.
+- Modified etcpal_netint and etcpal_inet to make more meaningful use of network
+  interface indexes, for portability and compatibility with IPv6.
+- etcpal/pdu -> etcpal/acn_pdu, etcpal/root_layer_pdu -> etcpal/acn_rlp. API
+  constructs have prefixes changed from `etcpal_` to `acn_` for clarity.
+
+### Removed
+- etcpal/bool module. This module is not necessary given our target platform
+  and toolchain requirements.
+- etcpal/int module. This module is not necessary given our target platform and
+  toolchain requirements.
+
 ## [0.2.0] - 2019-05-29
+
+Note: This is a pre-release version. This version changelog is not exhaustive.
+
 ### Added
 - This CHANGELOG file.
 - lwpa_mempool: LWPA_MEMPOOL_DEFINE_ARRAY(), which allows a memory pool of
@@ -33,9 +78,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Visual Studio project files, as we now build with CMake.
 
 ## [0.1.0] - 2018-10-18
+
+Note: This is a pre-release version. This version changelog is not exhaustive.
+
 ### Added
 - Initial library modules, tests and documentation.
 
-[Unreleased]: https://github.com/ETCLabs/lwpa/compare/master...develop
-[0.2.0]: https://github.com/ETCLabs/lwpa/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/ETCLabs/lwpa/releases/tag/v0.1.0
+[Unreleased]: https://github.com/ETCLabs/EtcPal/compare/stable...develop
+[0.3.0]: https://github.com/ETCLabs/EtcPal/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/ETCLabs/EtcPal/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/ETCLabs/EtcPal/releases/tag/v0.1.0

CMakeLists.txt

@@ -2,42 +2,86 @@ cmake_minimum_required(VERSION 3.3)
 
 ########################## Global Project Attributes ##########################
 
-project(lwpa VERSION 0.2.0)
+project(EtcPal VERSION 0.3.0)
 
-if(PROJECT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
+# Sometimes the seems to be some weirdness with drive letter capitalization on Windows, so do a
+# case-insensitive comparision
+if(${CMAKE_HOST_SYSTEM_NAME} STREQUAL Windows)
+  string(TOLOWER ${PROJECT_SOURCE_DIR} PROJECT_SOURCE_DIR_LC)
+  string(TOLOWER ${CMAKE_SOURCE_DIR} CMAKE_SOURCE_DIR_LC)
+else()
+  set(PROJECT_SOURCE_DIR_LC ${PROJECT_SOURCE_DIR})
+  set(CMAKE_SOURCE_DIR_LC ${CMAKE_SOURCE_DIR})
+endif()
+
+# Set options based on whether this project is being built on its own, or added as a dependency to
+# another project via add_subdirectory(). In the latter case, we don't override any global compile
+# options, or build tests or examples by default.
+if(PROJECT_SOURCE_DIR_LC STREQUAL CMAKE_SOURCE_DIR_LC)
   if (MSVC)
-    add_compile_options(/W4)
+    add_compile_options(/W4 /permissive-)
   elseif("${CMAKE_CXX_COMPILER_ID}" MATCHES "Clang" OR "${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU")
-    add_compile_options(-Wall -Wconversion)
+    add_compile_options(-Wall)
     if("${CMAKE_CXX_COMPILER_ID}" MATCHES "Clang")
       add_compile_options(-Wno-sign-conversion)
     else()
       add_compile_options(-Wno-sign-compare)
     endif()
   endif()
 
-  list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/tools/cmake)
+  # Allow folder grouping in generated IDE projects
+  set_property(GLOBAL PROPERTY USE_FOLDERS ON)
+
+  # Add a target to run Clang Format
+  file(GLOB_RECURSE FILES_TO_REFORMAT 
+    examples/*.c
+    examples/*.cpp
+    examples/*.h
+    include/*.h
+    src/*.c
+    src/*.cpp
+    src/*.h
+    tests/*.c
+    tests/*.cpp
+    tests/*.h
+  )
+  add_custom_target(reformat_all COMMAND clang-format -i ${FILES_TO_REFORMAT})
+  set_target_properties(reformat_all PROPERTIES FOLDER tools)
+
+  set(OPTION_DEFAULTS ON)
+else()
+  set(OPTION_DEFAULTS OFF)
 endif()
 
-option(LWPA_BUILD_MOCK_LIB "Build the lwpa_mock library" OFF)
-if(LWPA_BUILD_MOCK_LIB)
+set(ETCPAL_ROOT ${CMAKE_CURRENT_LIST_DIR})
+
+option(ETCPAL_BUILD_MOCK_LIB "Build the EtcPalMock library" OFF)
+option(ETCPAL_BUILD_TESTS "Build the EtcPal unit tests" OFF)
+option(ETCPAL_BUILD_EXAMPLES "Build the EtcPal example apps" OFF)
+
+option(ETCPAL_EXPLICITLY_DISABLE_EXCEPTIONS "Disable throwing of exceptions throughout the EtcPal C++ headers" OFF)
+
+# Platform support
+include(${PROJECT_SOURCE_DIR}/cmake/etcpal-os.cmake)
+
+if(ETCPAL_BUILD_MOCK_LIB OR ETCPAL_BUILD_TESTS)
   add_subdirectory(external/fff)
 endif()
 
-# Main library
+################################# Main library ################################
 
 add_subdirectory(src)
 
-if(PROJECT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
-  set(OPTION_DEFAULTS ON)
-else()
-  set(OPTION_DEFAULTS OFF)
-endif()
-
-# Tests
+#################################### Tests ####################################
 
-option(LWPA_BUILD_TESTS "Build the lwpa unit tests" ${OPTION_DEFAULTS})
-if(LWPA_BUILD_TESTS)
+if(ETCPAL_BUILD_TESTS)
+  add_subdirectory(external/unity)
   enable_testing()
   add_subdirectory(tests)
 endif()
+
+################################## Examples ###################################
+
+if(ETCPAL_BUILD_EXAMPLES)
+  add_subdirectory(examples)
+endif()

CONTRIBUTING.md

@@ -1,21 +1,52 @@
-# Contributing to lwpa
+# Contributing to EtcPal
 
-Thank you for your interest in contributing to the lwpa project!
+Thank you for your interest in contributing to the EtcPal project!
 
 ## Pull requests
 
-The lwpa library is currently in very early development. In order to keep
-things as stable as possible, we are not accepting pull requests at this time.
+Thanks for your interest in contributing code to the EtcPal library!
+
+### Building and Debugging the Library
+
+Check out the relevant [docs page](https://etclabs.github.io/EtcPal/docs/head/building_etcpal.html)
+for how to build EtcPal.
+
+When configuring with CMake, you will want to define `ETCPAL_BUILD_TESTS=ON` so that you can check
+that the unit tests pass as you modify the EtcPal library. This adds a few unit test executable
+targets to the build; you can run them all at once using CTest by just typing `ctest` in the build
+directory (or `ctest -C [configuration]` for a multi-config CMake generator).
+
+The EtcPal example applications can help provide immediate debugging feedback for changes made to
+the library. Enable them by configuring with `ETCPAL_BUILD_EXAMPLES=ON`.
+
+### Adding New Features
+
+EtcPal has a strictly-controlled scope in order to keep it lightweight and prevent it from becoming
+a monolithic catch-all. If your pull request adds a new feature or module to EtcPal, know that it
+might not be accepted for this reason.
+
+If you are adding a platform-abstraction feature, it is unlikely to be accepted unless it is ported
+for all platforms that EtcPal supports. For feature requests, it might be better to 
+[open an issue](https://github.com/ETCLabs/EtcPal/issues) so that the feature can be discussed by
+EtcPal maintainers before developing it.
+
+### Before Opening a Pull Request
+
+* Make sure the unit tests pass
+* If possible, test on multiple platforms
+* Add unit tests if applicable for any regressions or new features you have added to the library
+  + (This is not necessary if just modifying the example apps as they do not have test coverage)
+* Format the code you've touched using clang-format (CMake creates a convenient target `reformat_all`
+  which runs clang-format on all of the EtcPal sources if it is available on your PATH)
 
 ## Reporting issues
 
 ### Check to make sure your issue isn't already known
 
-If you have identified a reproducible bug or missing feature, please do the
-following before opening an issue:
+If you have identified a reproducible bug or missing feature, please do the following before
+opening an issue:
 
-* Make sure the bug or feature is not covered as a known issue in the README or
-  documentation.
+* Make sure the bug or feature is not covered as a known issue in the README or documentation.
 * Make sure the bug or feature is not covered in an existing open issue.
 
 ### Write a comprehensive bug report
@@ -25,6 +56,6 @@ A good bug report includes the following:
 * Which library code module(s) you were using and the library's version
 * A set of steps to reproduce the issue, in order
 * What you expected to see, and what happened instead
-* If the bug has occured in code you wrote that uses the lwpa library, please
-  provide code snippets and try to reduce to a minimal reproducible example.
-* Any logging output that was produced when the issue occurred
+* If the bug has occured in code you wrote that uses the EtcPal library, please provide code
+  snippets and try to reduce to a minimal reproducible example.
+* Any logging output that was produced when the issue occurred

README.md

@@ -1,35 +1,69 @@
-# LightWeight Platform Abstraction
+# EtcPal: ETC Platform Abstraction Layer
 
-[![Build Status](https://dev.azure.com/ETCLabs/lwpa/_apis/build/status/ETCLabs.lwpa?branchName=develop)](https://dev.azure.com/ETCLabs/lwpa/_build/latest?definitionId=1&branchName=develop)
+| Test Platform | Build & Test Status |
+|---------------|:-------------------:|
+| FreeRTOS+lwIP | [![Build & Test Status][freertos-lwip-build-badge]][azure-devops-link] |
+| iOS           | [![Build Status][ios-build-badge]][azure-devops-link] |
+| Linux         | [![Build & Test Status][linux-build-badge]][azure-devops-link] |
+| macOS         | [![Build & Test Status][macos-build-badge]][azure-devops-link] |
+| MQX           | [![Build & Test Status][mqx-build-badge]][azure-devops-link] |
+| Windows       | [![Build & Test Status][win-build-badge]][azure-devops-link] |
 
-This repository contains the LightWeight Platform Abstraction (lwpa) library,
-which supports other open-source libraries by [ETC](http://www.etcconnect.com).
+[freertos-lwip-build-badge]: https://dev.azure.com/ETCLabs/EtcPal/_apis/build/status/ETCLabs.EtcPal?branchName=develop&stageName=Build%20and%20Test%20EtcPal&jobName=FreeRTOS%2FlwIP
+[ios-build-badge]: https://dev.azure.com/ETCLabs/EtcPal/_apis/build/status/ETCLabs.EtcPal?branchName=develop&stageName=Build%20and%20Test%20EtcPal&jobName=iOS
+[linux-build-badge]: https://dev.azure.com/ETCLabs/EtcPal/_apis/build/status/ETCLabs.EtcPal?branchName=develop&stageName=Build%20and%20Test%20EtcPal&jobName=Linux
+[macos-build-badge]: https://dev.azure.com/ETCLabs/EtcPal/_apis/build/status/ETCLabs.EtcPal?branchName=develop&stageName=Build%20and%20Test%20EtcPal&jobName=macOS
+[mqx-build-badge]: https://dev.azure.com/ETCLabs/EtcPal/_apis/build/status/ETCLabs.EtcPal?branchName=develop&stageName=Build%20and%20Test%20EtcPal&jobName=MQX
+[win-build-badge]: https://dev.azure.com/ETCLabs/EtcPal/_apis/build/status/ETCLabs.EtcPal?branchName=develop&stageName=Build%20and%20Test%20EtcPal&jobName=Windows
+[azure-devops-link]: https://dev.azure.com/ETCLabs/EtcPal/_build/latest?definitionId=4&branchName=develop 
 
-The lwpa library serves two main purposes:
 
-* Provides a platform-neutral interface for common system calls, in order to
-  simplify the writing of platform-neutral software libraries.
-* Provides a common location for utilities that are used by multiple other
-  software libraries.
+This repository contains ETC's Platform Abstraction Layer (PAL), which supports other open-source
+libraries by [ETC](http://www.etcconnect.com).
+
+ETC develops many software products which target a range of platforms from full desktop OS down to
+32-bit microcontrollers. Because of this, there is a need for ETC's software libraries to be highly
+portable. The EtcPal library serves this purpose in two main ways:
+
+* Provides a platform-neutral interface for common system calls, in order to simplify the writing
+  of platform-neutral software libraries.
+* Provides a common location for utilities that are used by multiple other software libraries.
+
+## Docs
+
+EtcPal's API documentation is located [here](https://etclabs.github.io/EtcPal/docs/head). The
+"modules" entry on the sidebar provides module-by-module documentation.
 
 ## Platform Ports
 
-lwpa is currently ported for the following platforms:
+EtcPal is currently ported for the following platforms:
++ FreeRTOS (OS abstraction only)
++ Linux
++ lwIP (Network abstraction only)
++ macOS
 + Microsoft Windows
-+ MQX RTOS
++ MQX
+
+EtcPal is also buildable in no-OS (bare-metal) environments, with its platform-neutral utility
+functionality still available.
 
 ## Building
 
-lwpa is typically included as a dependency by other software libraries.
-However, if you would like to build lwpa on its own as a static lib, there are
-instructions in the [documentation](https://etclabs.github.io/lwpa).
+EtcPal is typically included as a dependency by other software libraries. However, if you would
+like to build EtcPal on its own, there are instructions in the
+[documentation](https://etclabs.github.io/EtcPal).
+
+## License
+
+EtcPal is licensed under the Apache License 2.0. EtcPal also incorporates some third-party software
+with different license terms, disclosed in ThirdPartySoftware.txt in the directory containing this
+README file. 
 
 ## About this ETCLabs Project
 
-lwpa is official, open-source software developed by ETC employees and is
-designed to interact with ETC products. For challenges using, integrating,
-compiling, or modifying this software, we encourage posting on the
-[issues page](https://github.com/ETCLabs/lwpa/issues) of this project.
+EtcPal is official, open-source software developed by ETC employees and is designed to interact
+with ETC products. For challenges using, integrating, compiling, or modifying this software, we
+encourage posting on the [issues page](https://github.com/ETCLabs/EtcPal/issues) of this project.
 
 Before posting an issue or opening a pull request, please read the
 [contribution guidelines](./CONTRIBUTING.md).