Add examples directory (#2083)

Add the beginnings of an `examples` directory structure that will help
demonstrate how to use the StableHLO library.

At the moment I've only added a c++ example, and a simple one at that
but the directory structure should indicate that we can support Python
in the future.

* Added a meta library 'stablehlo_lib' that you can link against which
should eventually include everything
* Added the add stablehlo example
* Added a simple README

```console
❯ ./build/examples/c++/stablehlo-add
module @test_module {
  func.func @main(%arg0: tensor<3x4xf32>, %arg1: tensor<3x4xf32>) -> tensor<3x4xf32> {
    %0 = stablehlo.add %arg0, %arg1 : tensor<3x4xf32>
    %1 = stablehlo.add %arg0, %arg1 : tensor<3x4xf32>
    return %1 : tensor<3x4xf32>
  }
}
```

Author: Farid Zakaria

CMakeLists.txt

@@ -187,3 +187,4 @@ add_custom_target(check-stablehlo-quick)
 add_dependencies(check-stablehlo-ci check-stablehlo-quick)
 
 add_subdirectory(stablehlo)
+add_subdirectory(examples)

examples/CMakeLists.txt

@@ -0,0 +1,15 @@
+# Copyright 2024 The TensorFlow Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+add_subdirectory(c++)

examples/c++/BUILD.bazel

@@ -0,0 +1,45 @@
+# Copyright 2023 The StableHLO Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+load("@rules_cc//cc:defs.bzl", "cc_binary", "cc_test")
+
+package(
+    default_visibility = ["//visibility:public"],
+    licenses = ["notice"],
+)
+
+cc_binary(
+    name = "stablehlo-add",
+    srcs = [
+        "stablehlo_add.cpp",
+    ],
+    deps = [
+        "//:stablehlo_ops",
+        "@llvm-project//mlir:FuncDialect",
+        "@llvm-project//mlir:IR",
+        "@llvm-project//mlir:QuantOps",
+    ],
+)
+
+cc_test(
+    name = "stablehlo-add_test",
+    srcs = [
+        "stablehlo_add.cpp",
+    ],
+    deps = [
+        "//:stablehlo_ops",
+        "@llvm-project//mlir:FuncDialect",
+        "@llvm-project//mlir:IR",
+        "@llvm-project//mlir:QuantOps",
+    ],
+)

examples/c++/CMakeLists.txt

@@ -0,0 +1,29 @@
+# Copyright 2024 The StableHLO Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# TODO(fzakaria): As we think about adding more tests we should consider
+# making this a function to be DRY.
+add_executable(stablehlo-add stablehlo_add.cpp)
+llvm_update_compile_flags(stablehlo-add)
+target_link_libraries(stablehlo-add PRIVATE StablehloOps)
+
+mlir_check_all_link_libraries(stablehlo-add)
+add_custom_target(stablehlo-add-test
+  COMMAND stablehlo-add
+  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  COMMENT "Executing stablehlo-add to validate it works."
+  DEPENDS
+    stablehlo-add
+)
+add_dependencies(check-stablehlo-quick stablehlo-add-test)

examples/c++/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+This directory should contain a series of examples as a starting point
+for how to use StableHLO.
+
+Note: If you have a great example to highlight, we welcome contributions!
+
+* [stablehlo_add](./stablehlo_add.cpp): A simple example that demonstrates
+how to use the StableHLO library to add two numbers.

examples/c++/stablehlo_add.cpp

@@ -0,0 +1,68 @@
+/* Copyright 2022 The StableHLO Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+==============================================================================*/
+#include "mlir/Dialect/Func/IR/FuncOps.h"
+#include "mlir/Dialect/Quant/QuantOps.h"
+#include "mlir/IR/BuiltinOps.h"
+#include "mlir/IR/BuiltinTypes.h"
+#include "mlir/IR/Verifier.h"
+#include "stablehlo/dialect/StablehloOps.h"
+
+int main() {
+  mlir::MLIRContext context;
+
+  /** create module **/
+  mlir::OwningOpRef<mlir::ModuleOp> module =
+      mlir::ModuleOp::create(mlir::UnknownLoc::get(&context));
+  module->getContext()->loadDialect<mlir::func::FuncDialect>();
+  module->getContext()->loadDialect<mlir::stablehlo::StablehloDialect>();
+  module->getContext()->loadDialect<mlir::quant::QuantizationDialect>();
+  module->setName("test_module");
+
+  /** create function **/
+  // create function argument and result types
+  mlir::Type arg0 =
+      mlir::RankedTensorType::get({3, 4}, mlir::FloatType::getF32(&context));
+  auto func_type = mlir::FunctionType::get(&context, {arg0, arg0}, {arg0});
+
+  // create the function and map arguments.
+  llvm::ArrayRef<mlir::NamedAttribute> attrs;
+  auto function = mlir::func::FuncOp::create(mlir::UnknownLoc::get(&context),
+                                             "main", func_type, attrs);
+  function.setVisibility(mlir::func::FuncOp::Visibility::Public);
+  module->push_back(function);
+
+  // create function block with add operations
+  mlir::Block* block = function.addEntryBlock();
+  llvm::SmallVector<mlir::Value, 4> arguments(block->args_begin(),
+                                              block->args_end());
+  mlir::OpBuilder block_builder = mlir::OpBuilder::atBlockEnd(block);
+  mlir::Location loc = block_builder.getUnknownLoc();
+
+  llvm::SmallVector<mlir::NamedAttribute, 10> attributes;
+  block_builder.create<mlir::stablehlo::AddOp>(loc, arguments, attributes)
+      .getOperation();
+
+  mlir::Operation* op =
+      block_builder
+          .create<mlir::stablehlo::AddOp>(loc, arg0, arguments, attributes)
+          .getOperation();
+  block_builder.create<mlir::func::ReturnOp>(loc, op->getResult(0));
+
+  // verify the module and dump
+  assert(mlir::succeeded(mlir::verify(module.get())));
+  module->dump();
+
+  return 0;
+}