Skip to content

Commit

Permalink
Merge pull request #44 from open205/libtk205-release-0
Browse files Browse the repository at this point in the history
Libtk205 release 0
  • Loading branch information
nealkruis authored Dec 1, 2022
2 parents aa67217 + 33d1c21 commit c69fc7c
Show file tree
Hide file tree
Showing 32 changed files with 1,150 additions and 416 deletions.
21 changes: 12 additions & 9 deletions .github/workflows/build-and-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,37 +6,40 @@ jobs:
build:
name: Build
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
python-version: ["3.6", "3.7", "3.8", "3.9"]
python-version: ["3.7", "3.8", "3.9", "3.10"]
defaults:
run:
shell: bash
runs-on: ${{ matrix.os }}
steps:
- name: Checkout
uses: actions/checkout@v2
uses: actions/checkout@v3
with:
submodules: recursive
- name: Setup python ${{ matrix.python-version }}
uses: actions/setup-python@v2
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- name: Install Poetry
uses: snok/install-poetry@v1.1.1
uses: snok/install-poetry@v1.3.1
with:
version: 1.2.2
virtualenvs-create: true
virtualenvs-in-project: true
- name: Load cached venv if cache exists
id: cached-poetry-dependencies
uses: actions/cache@v2
uses: actions/cache@v3
with:
path: .venv
key: poetry-cache-v3-${{ matrix.os }}-py${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
key: venv-${{ matrix.os }}-py${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
- name: Install dependencies if cache does not exist
run: poetry install
if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
- name: Build and test
run: |
source $VENV
poetry run doit
run: poetry run doit
- name: Export libtk205 source
run: cmake -DPA_TOKEN="${{secrets.CI_PA_TOKEN}}" -DPROJECT_SOURCE_DIR="${{github.workspace}}/libtk205" -P "${{github.workspace}}/libtk205/cmake/update_lib_repo.cmake"

6 changes: 6 additions & 0 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
[submodule "schema-205"]
path = schema-205
url = https://github.com/open205/schema-205
[submodule "libtk205/vendor/json"]
path = libtk205/vendor/json
url = https://github.com/nlohmann/json.git
[submodule "libtk205/vendor/btwxt"]
path = libtk205/vendor/btwxt
url = https://github.com/bigladder/btwxt.git
28 changes: 28 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
cmake_minimum_required(VERSION 3.14.0)
project(toolkit-205)

if (USE_CLANGTIDY_STATIC_ANALYSIS)
set(CMAKE_CXX_CLANG_TIDY
clang-tidy;
-checks=-*,clang-analyzer-*,cppcoreguidelines-*
)
endif()

# Set a default build type if none was specified
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
message(STATUS "Setting build type to 'Release' as none was specified.")
set(CMAKE_BUILD_TYPE Release CACHE STRING "Choose the type of build." FORCE)
# Set the possible values of build type for cmake-gui
set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release"
"MinSizeRel" "RelWithDebInfo")
endif()

option( BUILD_TK205_TESTING "Build libtk205 testing targets" ON )

# Set up testing/coverage
if (BUILD_TK205_TESTING)
set(TEST205_INPUT_EXAMPLES_DIR "${PROJECT_SOURCE_DIR}/schema-205")
enable_testing()
endif()

add_subdirectory(libtk205)
11 changes: 11 additions & 0 deletions LICENSE.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
Copyright (c) 2022 Big Ladder Software, LLC

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
62 changes: 23 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,33 +3,12 @@
Toolkit 205
===========

A toolkit to facilitate the adoption of the ASHRAE Standard 205P data exchange specification.
A toolkit to facilitate the adoption of the ASHRAE Standard 205, "Representation of Performance Data for HVAC&R and Other Facility Equipment", data exchange specification. Learn more about ASHRAE Standard 205 at https://data.ashrae.org/standard205/.

**Disclaimer:** While this toolkit is developed in conjunction with the ASHRAE Standard 205 project committee, it is not an official ASHRAE product or a part of the standard.

**Warning!** As the proposed ASHRAE Standard 205P has not yet been published, the content in this repository is subject to change and should be considered unstable for application development.

About ASHRAE 205
----------------

ASHRAE Standard 205P is "Standard Representation of Performance Simulation Data for HVAC&R and Other Facility Equipment". While the standard is not yet published, public reviews are available at [ASHRAE's online review portal](https://osr.ashrae.org/default.aspx).

The stated purpose of ASHRAE Standard 205 is:

> To facilitate sharing of equipment characteristics for performance simulation by defining standard representations such as data models, data formats, and automation interfaces.
The Standard is intended to support the following use cases:

- **Data Publication** Data publishers (typically equipment manufacturers) use representation specifications to guide implementation of data writing and validity testing software that produces correctly-formed representation files.

- **Application Development** Application developers use representation specifications to guide implementation of software that correctly reads representation data. Such implementations may include validity tests and developers may use representation specification example data for testing purposes.

- **Data Application** Application users use representation specifications to understand and check representation data. Data exchange will generally be automated but the availability of representation specifications facilitates additional data checking when needed.

Generally, a data publisher (e.g., manufacturer) provides an ASHRAE Standard 205 representation of a specific piece of equipment that the application user can load into compliant performance simulation software.

Building
--------
Building the Toolkit
--------------------

Toolkit 205 uses git submodules. To clone the submodules, you will either have to:

Expand All @@ -39,32 +18,37 @@ Toolkit 205 uses git submodules. To clone the submodules, you will either have t

or

2. do a recursive submodule update after cloneing this repository:
2. do a recursive submodule update after cloning this repository:

`git submodule update --init --recursive`

We are currently supporting python 3.x.
We are currently supporting python 3.7 and higher.

In order to contribute to Toolkit 205, you will need to set up a consistent virtual environment for testing.
This project uses `pipenv` to create a virtual python environment and install the required dependencies.
Install `pipenv` through `pip`:
This project uses [Poetry](https://python-poetry.org/docs/#installation) python package management tool. Once you have Poetry installed you can install the dependencies using:

`pip install pipenv`
`poetry install`

With `pipenv` installed, you may now create the virtual environment (defined in the `Pipfile`) where you will install the project and developer dependencies:
You can test your installation using:

`pipenv install --dev`
`poetry run doit`

### Products

Finally, you can build (generate the schema, translate examples, generate templates, and generate web content) and test the toolkit:
tk205 is both a python module and a command line tool.

`pipenv run doit`
Building the Toolkit C++ library
--------------------------------

### Products
The toolkit can additionally build a C++ library suitable for import into C++ modeling tools. The library (libtk205) uses elements of the schema-205 submodule to auto-generate source code for Representation Specifications, and includes other source files from this repository.

tk205 is both a python module and a command line tool.
To build the library, use

`cmake -B build`

to generate build files for an "out-of-source" build directory, then

`cmake --build build --config [Debug/Release]`

Example Usage
-------------
to build libtk205.

TODO
**Note:** Because the tests for libtk205 automatically clean all auto-generated files after the build, the cmake generator must be run fresh each time. This ensures that no Representations are out of date.
25 changes: 24 additions & 1 deletion dodo.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
EXAMPLES_OUTPUT_PATH = os.path.join(BUILD_PATH,"examples")
TEMPLATE_OUTPUT_PATH = os.path.join(BUILD_PATH,"templates")
TEMPLATE_CONFIG = os.path.join('config','templates.json')
LIB_BUILD_PATH = os.path.join(BUILD_PATH,"libtk205")
TK205_SOURCE_PATH = 'tk205'
SCHEMA205_SOURCE_PATH = os.path.join("schema-205","schema205")

Expand Down Expand Up @@ -155,7 +156,9 @@ def task_test():
return {
'task_dep': ['build_schema','cbor','yaml','xlsx','json'],
'file_dep': cbor_examples + yaml_examples + xlsx_examples + json_examples,
'actions': ['pytest -v test']
'actions': [
'pytest -v test',
]
}

def task_web():
Expand All @@ -165,3 +168,23 @@ def task_web():
'file_dep': cbor_examples + yaml_examples + xlsx_examples + json_examples + template_files, # Add markdown content
'actions': ['python web/web-content.py']
}

def task_libtk205():
'''Build libtk205'''
return {
'task_dep': ['build_schema'],
'actions': [
(create_folder, [LIB_BUILD_PATH]),
f'cmake -B {LIB_BUILD_PATH}',
f'cmake --build {LIB_BUILD_PATH} --config Release'
],
}

def task_libtk205_tests():
'''Performs unit tests and example file validation tests'''
return {
'task_dep': ['libtk205'],
'actions': [
f'cd {LIB_BUILD_PATH} && ctest',
],
}
63 changes: 63 additions & 0 deletions libtk205/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
project(libtk205)

include(CTest)
set(JSON_BuildTests OFF CACHE INTERNAL "")

# include_directories adds locations to the -I command line
include_directories(${CMAKE_CURRENT_SOURCE_DIR}/vendor/btwxt/src)
include_directories(${CMAKE_CURRENT_SOURCE_DIR}/vendor/json/single_include)
include_directories(${CMAKE_CURRENT_SOURCE_DIR}/vendor/json/include)
include_directories(${CMAKE_CURRENT_SOURCE_DIR}/include)
include_directories(${CMAKE_CURRENT_SOURCE_DIR}/../schema-205/build/include)
include_directories(${CMAKE_CURRENT_SOURCE_DIR}/../schema-205/schema205/src)

file(GLOB RS_schemas "${PROJECT_SOURCE_DIR}/../schema-205/schema-source/*.schema.yaml")

foreach(schema IN LISTS RS_schemas)
string(REGEX REPLACE "${PROJECT_SOURCE_DIR}/../schema-205/schema-source/(.*).schema.yaml" "\\1" schema_name "${schema}")
string(TOLOWER ${schema_name} schema_name)
list(APPEND rs_headers "${PROJECT_SOURCE_DIR}/../schema-205/build/include/${schema_name}.h")
list(APPEND rs_src "${PROJECT_SOURCE_DIR}/../schema-205/build/cpp/${schema_name}.cpp")
if (schema_name MATCHES "rs.*")
list(APPEND factory_headers "${PROJECT_SOURCE_DIR}/../schema-205/build/include/${schema_name}_factory.h")
list(APPEND factory_src "${PROJECT_SOURCE_DIR}/../schema-205/build/cpp/${schema_name}_factory.cpp")
endif()
endforeach()

list(APPEND lib_headers "${CMAKE_CURRENT_SOURCE_DIR}/include/typeinfo_205.h"
"${CMAKE_CURRENT_SOURCE_DIR}/include/loadobject_205.h"
"${CMAKE_CURRENT_SOURCE_DIR}/include/error_handling_tk205.h")

add_custom_command(OUTPUT ${rs_headers} ${rs_src} ${lib_headers} ${lib_src}
COMMAND poetry run doit cpp
DEPENDS ${RS_schemas}
COMMENT "Generate libtk205 files from YAML schema"
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/../schema-205")

set (SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/src/error_handling_tk205.cpp"
"${rs_headers}"
"${rs_src}"
"${factory_headers}"
"${factory_src}"
"${lib_headers}"
"${lib_src}")

add_library(libtk205 ${SOURCES})

# add_custom_target(update_lib_repo ALL
# COMMAND ${CMAKE_COMMAND} "-DPROJECT_SOURCE_DIR=${PROJECT_SOURCE_DIR}" -P "${PROJECT_SOURCE_DIR}/cmake/update_lib_repo.cmake"
# VERBATIM)
# add_dependencies(update_lib_repo libtk205)

add_subdirectory(vendor)

if (BUILD_TK205_TESTING)
add_compile_definitions(TEST205_INPUT_EXAMPLES_DIR="${TEST205_INPUT_EXAMPLES_DIR}")
add_subdirectory(test)
endif()

set(CPACK_PROJECT_NAME ${PROJECT_NAME})
set(CPACK_PROJECT_VERSION ${PROJECT_VERSION})
include(CPack)
12 changes: 12 additions & 0 deletions libtk205/cmake/copy_autogenerated_files.cmake
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Copy headers, for classes that must be distributed (not factories), into the project
# include directory

file(GLOB autogenerated_factories "${PROJECT_SOURCE_DIR}/../schema-205/build/include/*factory.h")
file(GLOB autogenerated_headers "${PROJECT_SOURCE_DIR}/../schema-205/build/include/*.h")
foreach(filename ${autogenerated_factories})
list(REMOVE_ITEM autogenerated_headers ${filename})
endforeach(filename)

foreach(filename ${autogenerated_headers})
configure_file(${filename} ${PROJECT_SOURCE_DIR}/include COPYONLY)
endforeach(filename)
7 changes: 7 additions & 0 deletions libtk205/cmake/copy_base_class_files.cmake
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Copy all autogenerated source (cpp) files into build directory

file(GLOB template_generated_files "${PROJECT_SOURCE_DIR}/../schema-205/schema205/src/*.h")

foreach(filename ${template_generated_files})
configure_file(${filename} ${PROJECT_SOURCE_DIR}/include COPYONLY)
endforeach(filename)
Loading

0 comments on commit c69fc7c

Please sign in to comment.