Initial Objective-C API (microsoft#7366)

Initial implementation of an Objective-C API.

Author: edgchen1

Diff for: cmake/CMakeLists.txt

@@ -65,6 +65,7 @@ option(onnxruntime_MSVC_STATIC_RUNTIME "Compile for the static CRT" OFF)
 option(onnxruntime_GCC_STATIC_CPP_RUNTIME "Compile for the static libstdc++" OFF)
 option(onnxruntime_BUILD_UNIT_TESTS "Build ONNXRuntime unit tests" ON)
 option(onnxruntime_BUILD_CSHARP "Build C# library" OFF)
+option(onnxruntime_BUILD_OBJC "Build Objective-C library" OFF)
 option(onnxruntime_USE_PREINSTALLED_EIGEN "Use pre-installed EIGEN. Need to provide eigen_SOURCE_PATH if turn this on." OFF)
 option(onnxruntime_BUILD_BENCHMARKS "Build ONNXRuntime micro-benchmarks" OFF)
 
@@ -1574,6 +1575,11 @@ if (onnxruntime_ENABLE_PYTHON)
   include(onnxruntime_python.cmake)
 endif()
 
+if (onnxruntime_BUILD_OBJC)
+  message(STATUS "Objective-C Build is enabled")
+  include(onnxruntime_objectivec.cmake)
+endif()
+
 if (onnxruntime_BUILD_UNIT_TESTS)
   include(onnxruntime_unittests.cmake)
 endif()

Diff for: cmake/onnxruntime.cmake

@@ -79,7 +79,6 @@ endif()
 
 add_dependencies(onnxruntime onnxruntime_generate_def ${onnxruntime_EXTERNAL_DEPENDENCIES})
 target_include_directories(onnxruntime PRIVATE ${ONNXRUNTIME_ROOT})
-onnxruntime_add_include_to_target(onnxruntime)
 
 target_compile_definitions(onnxruntime PRIVATE VER_MAJOR=${VERSION_MAJOR_PART})
 target_compile_definitions(onnxruntime PRIVATE VER_MINOR=${VERSION_MINOR_PART})

Diff for: cmake/onnxruntime_common.cmake

@@ -119,10 +119,9 @@ target_include_directories(onnxruntime_common
     PRIVATE ${CMAKE_CURRENT_BINARY_DIR} ${ONNXRUNTIME_ROOT} ${eigen_INCLUDE_DIRS}
     # propagate include directories of dependencies that are part of public interface
     PUBLIC
-        $<TARGET_PROPERTY:safeint_interface,INTERFACE_INCLUDE_DIRECTORIES>
         ${OPTIONAL_LITE_INCLUDE_DIR})
 
-target_link_libraries(onnxruntime_common Boost::mp11)
+target_link_libraries(onnxruntime_common safeint_interface Boost::mp11)
 
 if(NOT WIN32)
   target_include_directories(onnxruntime_common PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/external/nsync/public")

Diff for: cmake/onnxruntime_objectivec.cmake

@@ -0,0 +1,124 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+if(${CMAKE_VERSION} VERSION_LESS "3.18")
+    message(FATAL_ERROR "CMake 3.18+ is required when building the Objective-C API.")
+endif()
+
+check_language(OBJC)
+if(CMAKE_OBJC_COMPILER)
+    enable_language(OBJC)
+else()
+    message(FATAL_ERROR "Objective-C is not supported.")
+endif()
+
+check_language(OBJCXX)
+if(CMAKE_OBJCXX_COMPILER)
+    enable_language(OBJCXX)
+else()
+    message(FATAL_ERROR "Objective-C++ is not supported.")
+endif()
+
+add_compile_options(
+    "$<$<COMPILE_LANGUAGE:OBJC,OBJCXX>:-Wall>"
+    "$<$<COMPILE_LANGUAGE:OBJC,OBJCXX>:-Wextra>")
+if(onnxruntime_DEV_MODE)
+    add_compile_options(
+        "$<$<COMPILE_LANGUAGE:OBJC,OBJCXX>:-Werror>")
+endif()
+
+set(OBJC_ROOT "${REPO_ROOT}/objectivec")
+
+set(OBJC_ARC_COMPILE_OPTIONS "-fobjc-arc" "-fobjc-arc-exceptions")
+
+# onnxruntime_objc target
+
+# these headers are the public interface
+# explicitly list them here so it is easy to see what is included
+set(onnxruntime_objc_headers
+    "${OBJC_ROOT}/include/onnxruntime.h"
+    "${OBJC_ROOT}/include/onnxruntime/ort_env.h"
+    "${OBJC_ROOT}/include/onnxruntime/ort_session.h"
+    "${OBJC_ROOT}/include/onnxruntime/ort_value.h")
+
+file(GLOB onnxruntime_objc_srcs
+    "${OBJC_ROOT}/src/*.h"
+    "${OBJC_ROOT}/src/*.m"
+    "${OBJC_ROOT}/src/*.mm")
+
+# files common to implementation and test targets
+set(onnxruntime_objc_common_srcs
+    "${OBJC_ROOT}/common/assert_arc_enabled.mm")
+
+source_group(TREE "${OBJC_ROOT}" FILES
+    ${onnxruntime_objc_headers}
+    ${onnxruntime_objc_srcs}
+    ${onnxruntime_objc_common_srcs})
+
+add_library(onnxruntime_objc SHARED
+    ${onnxruntime_objc_headers}
+    ${onnxruntime_objc_srcs}
+    ${onnxruntime_objc_common_srcs})
+
+target_include_directories(onnxruntime_objc
+    PUBLIC
+        "${OBJC_ROOT}/include"
+    PRIVATE
+        "${ONNXRUNTIME_ROOT}"
+        "${OBJC_ROOT}")
+
+find_library(FOUNDATION_LIB Foundation REQUIRED)
+
+target_link_libraries(onnxruntime_objc
+    PRIVATE
+        onnxruntime
+        safeint_interface
+        ${FOUNDATION_LIB})
+
+target_compile_options(onnxruntime_objc PRIVATE ${OBJC_ARC_COMPILE_OPTIONS})
+
+set_target_properties(onnxruntime_objc PROPERTIES
+    FRAMEWORK TRUE
+    VERSION "1.0.0"
+    SOVERSION "1.0.0"
+    FRAMEWORK_VERSION "A"
+    PUBLIC_HEADER "${onnxruntime_objc_headers}"
+    FOLDER "ONNXRuntime"
+    CXX_STANDARD 17) # TODO remove when everything else moves to 17
+
+if(onnxruntime_BUILD_UNIT_TESTS)
+    find_package(XCTest REQUIRED)
+
+    # onnxruntime_test_objc target
+
+    file(GLOB onnxruntime_objc_test_srcs
+        "${OBJC_ROOT}/test/*.h"
+        "${OBJC_ROOT}/test/*.m"
+        "${OBJC_ROOT}/test/*.mm")
+
+    source_group(TREE "${OBJC_ROOT}" FILES ${onnxruntime_objc_test_srcs})
+
+    xctest_add_bundle(onnxruntime_objc_test onnxruntime_objc
+        ${onnxruntime_objc_headers}
+        ${onnxruntime_objc_test_srcs}
+        ${onnxruntime_objc_common_srcs})
+
+    target_include_directories(onnxruntime_objc_test
+        PRIVATE
+            "${OBJC_ROOT}")
+
+    target_compile_options(onnxruntime_objc_test PRIVATE ${OBJC_ARC_COMPILE_OPTIONS})
+
+    set_target_properties(onnxruntime_objc_test PROPERTIES
+        FOLDER "ONNXRuntimeTest")
+
+    add_custom_command(TARGET onnxruntime_objc_test POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy_directory
+            "${OBJC_ROOT}/test/testdata"
+            "$<TARGET_BUNDLE_CONTENT_DIR:onnxruntime_objc_test>/Resources/testdata")
+
+    xctest_add_test(XCTest.onnxruntime_objc_test onnxruntime_objc_test)
+
+    set_property(TEST XCTest.onnxruntime_objc_test APPEND PROPERTY
+        ENVIRONMENT "DYLD_LIBRARY_PATH=$<TARGET_FILE_DIR:onnxruntime>")
+endif()

Diff for: cmake/onnxruntime_providers.cmake

@@ -1041,7 +1041,7 @@ if (onnxruntime_USE_ROCM)
   endif()
   # During transition to separate hipFFT repo, put hipfft/include early
   target_include_directories(onnxruntime_providers_rocm PRIVATE ${onnxruntime_ROCM_HOME}/hipfft/include ${onnxruntime_ROCM_HOME}/include ${onnxruntime_ROCM_HOME}/hipcub/include ${onnxruntime_ROCM_HOME}/hiprand/include ${onnxruntime_ROCM_HOME}/rocrand/include)
-  target_include_directories(onnxruntime_providers_rocm PRIVATE ${ONNXRUNTIME_ROOT} ${CMAKE_CURRENT_BINARY_DIR}/amdgpu/onnxruntime ${MPI_INCLUDE_DIRS} ${SAFEINT_INCLUDE_DIR} ${ONNXRUNTIME_ROOT}/../cmake/external/eigen)
+  target_include_directories(onnxruntime_providers_rocm PRIVATE ${ONNXRUNTIME_ROOT} ${CMAKE_CURRENT_BINARY_DIR}/amdgpu/onnxruntime ${MPI_INCLUDE_DIRS} ${ONNXRUNTIME_ROOT}/../cmake/external/eigen)
 
   if (onnxruntime_ENABLE_TRAINING)
     target_include_directories(onnxruntime_providers_rocm PRIVATE ${ORTTRAINING_ROOT} ${CMAKE_CURRENT_BINARY_DIR}/amdgpu/orttraining)

Diff for: docs/Coding_Conventions_and_Standards.md

@@ -70,3 +70,8 @@ The [autopep8](https://pypi.org/project/autopep8/) tool can be used to automatic
 
 Editors such as PyCharm [(see here)](https://www.jetbrains.com/help/pycharm/code-inspection.html) and Visual Studio Code [(see here)](https://code.visualstudio.com/docs/python/linting#_flake8) can be configured to check for PEP8 issues. 
 
+## Objective-C/C++ Code Style
+
+Please follow the [Google Objective-C/C++ Style Guide](https://google.github.io/styleguide/objcguide.html).
+
+Clang-format can be used to format Objective-C/C++ code. The .clang-format file is in the repository root directory.

Diff for: include/onnxruntime/core/session/onnxruntime_c_api.h

@@ -157,7 +157,7 @@ ORT_RUNTIME_CLASS(Env);
 ORT_RUNTIME_CLASS(Status);  // nullptr for Status* indicates success
 ORT_RUNTIME_CLASS(MemoryInfo);
 ORT_RUNTIME_CLASS(IoBinding);
-ORT_RUNTIME_CLASS(Session);  //Don't call OrtReleaseSession from Dllmain (because session owns a thread pool)
+ORT_RUNTIME_CLASS(Session);  //Don't call ReleaseSession from Dllmain (because session owns a thread pool)
 ORT_RUNTIME_CLASS(Value);
 ORT_RUNTIME_CLASS(RunOptions);
 ORT_RUNTIME_CLASS(TypeInfo);
@@ -343,12 +343,12 @@ struct OrtApi {
   const char*(ORT_API_CALL* GetErrorMessage)(_In_ const OrtStatus* status)NO_EXCEPTION ORT_ALL_ARGS_NONNULL;
 
   /**
-     * \param out Should be freed by `OrtReleaseEnv` after use
+     * \param out Should be freed by `ReleaseEnv` after use
      */
   ORT_API2_STATUS(CreateEnv, OrtLoggingLevel logging_level, _In_ const char* logid, _Outptr_ OrtEnv** out);
 
   /**
-   * \param out Should be freed by `OrtReleaseEnv` after use
+   * \param out Should be freed by `ReleaseEnv` after use
    */
   ORT_API2_STATUS(CreateEnvWithCustomLogger, OrtLoggingFunction logging_function, _In_opt_ void* logger_param,
                   OrtLoggingLevel logging_level, _In_ const char* logid, _Outptr_ OrtEnv** out);
@@ -375,7 +375,7 @@ struct OrtApi {
                   _Inout_updates_all_(output_names_len) OrtValue** output);
 
   /**
-    * \return A pointer of the newly created object. The pointer should be freed by OrtReleaseSessionOptions after use
+    * \return A pointer of the newly created object. The pointer should be freed by ReleaseSessionOptions after use
     */
   ORT_API2_STATUS(CreateSessionOptions, _Outptr_ OrtSessionOptions** options);
 
@@ -432,7 +432,7 @@ struct OrtApi {
   ORT_API2_STATUS(SetInterOpNumThreads, _Inout_ OrtSessionOptions* options, int inter_op_num_threads);
 
   /*
-  Create a custom op domain. After all sessions using it are released, call OrtReleaseCustomOpDomain
+  Create a custom op domain. After all sessions using it are released, call ReleaseCustomOpDomain
   */
   ORT_API2_STATUS(CreateCustomOpDomain, _In_ const char* domain, _Outptr_ OrtCustomOpDomain** out);
 
@@ -474,18 +474,18 @@ struct OrtApi {
   ORT_API2_STATUS(SessionGetOverridableInitializerCount, _In_ const OrtSession* sess, _Out_ size_t* out);
 
   /**
-   * \param out  should be freed by OrtReleaseTypeInfo after use
+   * \param out  should be freed by ReleaseTypeInfo after use
    */
   ORT_API2_STATUS(SessionGetInputTypeInfo, _In_ const OrtSession* sess, size_t index, _Outptr_ OrtTypeInfo** type_info);
 
   /**
-   * \param out  should be freed by OrtReleaseTypeInfo after use
+   * \param out  should be freed by ReleaseTypeInfo after use
    */
   ORT_API2_STATUS(SessionGetOutputTypeInfo, _In_ const OrtSession* sess, size_t index,
                   _Outptr_ OrtTypeInfo** type_info);
 
   /**
- * \param out  should be freed by OrtReleaseTypeInfo after use
+ * \param out  should be freed by ReleaseTypeInfo after use
  */
   ORT_API2_STATUS(SessionGetOverridableInitializerTypeInfo, _In_ const OrtSession* sess, size_t index,
                   _Outptr_ OrtTypeInfo** type_info);
@@ -501,7 +501,7 @@ struct OrtApi {
                   _Inout_ OrtAllocator* allocator, _Outptr_ char** value);
 
   /**
-   * \return A pointer to the newly created object. The pointer should be freed by OrtReleaseRunOptions after use
+   * \return A pointer to the newly created object. The pointer should be freed by ReleaseRunOptions after use
    */
   ORT_API2_STATUS(CreateRunOptions, _Outptr_ OrtRunOptions** out);
 
@@ -520,17 +520,17 @@ struct OrtApi {
   ORT_API2_STATUS(RunOptionsUnsetTerminate, _Inout_ OrtRunOptions* options);
 
   /**
-   * Create a tensor from an allocator. OrtReleaseValue will also release the buffer inside the output value
-   * \param out Should be freed by calling OrtReleaseValue
+   * Create a tensor from an allocator. ReleaseValue will also release the buffer inside the output value
+   * \param out Should be freed by calling ReleaseValue
    * \param type must be one of TENSOR_ELEMENT_DATA_TYPE_xxxx
    */
   ORT_API2_STATUS(CreateTensorAsOrtValue, _Inout_ OrtAllocator* allocator, _In_ const int64_t* shape, size_t shape_len,
                   ONNXTensorElementDataType type, _Outptr_ OrtValue** out);
 
   /**
    * Create a tensor with user's buffer. You can fill the buffer either before calling this function or after.
-   * p_data is owned by caller. OrtReleaseValue won't release p_data.
-   * \param out Should be freed by calling OrtReleaseValue
+   * p_data is owned by caller. ReleaseValue won't release p_data.
+   * \param out Should be freed by calling ReleaseValue
    */
   ORT_API2_STATUS(CreateTensorWithDataAsOrtValue, _In_ const OrtMemoryInfo* info, _Inout_ void* p_data,
                   size_t p_data_len, _In_ const int64_t* shape, size_t shape_len, ONNXTensorElementDataType type,
@@ -578,7 +578,7 @@ struct OrtApi {
   ORT_API2_STATUS(GetOnnxTypeFromTypeInfo, _In_ const OrtTypeInfo*, _Out_ enum ONNXType* out);
 
   /**
-     * The 'out' value should be released by calling OrtReleaseTensorTypeAndShapeInfo
+     * The 'out' value should be released by calling ReleaseTensorTypeAndShapeInfo
      */
   ORT_API2_STATUS(CreateTensorTypeAndShapeInfo, _Outptr_ OrtTensorTypeAndShapeInfo** out);
 
@@ -611,14 +611,14 @@ struct OrtApi {
   ORT_API2_STATUS(GetTensorShapeElementCount, _In_ const OrtTensorTypeAndShapeInfo* info, _Out_ size_t* out);
 
   /**
- * \param out Should be freed by OrtReleaseTensorTypeAndShapeInfo after use
+ * \param out Should be freed by ReleaseTensorTypeAndShapeInfo after use
  */
   ORT_API2_STATUS(GetTensorTypeAndShape, _In_ const OrtValue* value, _Outptr_ OrtTensorTypeAndShapeInfo** out);
 
   /**
  * Get the type information of an OrtValue
  * \param value
- * \param out The returned value should be freed by OrtReleaseTypeInfo after use
+ * \param out The returned value should be freed by ReleaseTypeInfo after use
  */
   ORT_API2_STATUS(GetTypeInfo, _In_ const OrtValue* value, _Outptr_result_maybenull_ OrtTypeInfo** out);
 
@@ -793,7 +793,7 @@ struct OrtApi {
   ORT_CLASS_RELEASE(Env);
   ORT_CLASS_RELEASE(Status);  // nullptr for Status* indicates success
   ORT_CLASS_RELEASE(MemoryInfo);
-  ORT_CLASS_RELEASE(Session);  //Don't call OrtReleaseSession from Dllmain (because session owns a thread pool)
+  ORT_CLASS_RELEASE(Session);  //Don't call ReleaseSession from Dllmain (because session owns a thread pool)
   ORT_CLASS_RELEASE(Value);
   ORT_CLASS_RELEASE(RunOptions);
   ORT_CLASS_RELEASE(TypeInfo);
@@ -1156,7 +1156,7 @@ struct OrtApi {
    * Use this in conjunction with DisablePerSessionThreads API or else the session will use
    * its own thread pools.
    *
-   * \param out should be freed by `OrtReleaseEnv` after use
+   * \param out should be freed by `ReleaseEnv` after use
    */
   ORT_API2_STATUS(CreateEnvWithCustomLoggerAndGlobalThreadPools, OrtLoggingFunction logging_function, _In_opt_ void* logger_param, OrtLoggingLevel logging_level,
                   _In_ const char* logid, _In_ const struct OrtThreadingOptions* tp_options, _Outptr_ OrtEnv** out);

Diff for: objectivec/common/assert_arc_enabled.mm

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+static_assert(__has_feature(objc_arc), "Objective-C ARC must be enabled.");

Diff for: objectivec/format_objc.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# formats Objective-C/C++ code
+
+set -e
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+clang-format -i $(find ${SCRIPT_DIR} -name "*.h" -o -name "*.m" -o -name "*.mm")
+

Diff for: objectivec/include/onnxruntime.h

@@ -0,0 +1,9 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+// this header contains the entire ONNX Runtime Objective-C API
+// the headers below can also be imported individually
+
+#import "onnxruntime/ort_env.h"
+#import "onnxruntime/ort_session.h"
+#import "onnxruntime/ort_value.h"

Diff for: objectivec/include/onnxruntime/ort_env.h

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * The ORT environment.
+ */
+@interface ORTEnv : NSObject
+
+- (nullable instancetype)init NS_UNAVAILABLE;
+
+/**
+ * Creates an ORT Environment.
+ *
+ * @param[out] error Optional error information set if an error occurs.
+ * @return The instance, or nil if an error occurs.
+ */
+- (nullable instancetype)initWithError:(NSError**)error NS_DESIGNATED_INITIALIZER;
+
+@end
+
+NS_ASSUME_NONNULL_END