[libc-commits] [libc] 9145bf1 - [libc] Add example programs and their CMake build and instructions.
Siva Chandra Reddy via libc-commits
libc-commits at lists.llvm.org
Fri Nov 4 01:31:20 PDT 2022
Author: Siva Chandra Reddy
Date: 2022-11-04T08:31:06Z
New Revision: 9145bf13b7df41d955efce6778994fb455d42d58
URL: https://github.com/llvm/llvm-project/commit/9145bf13b7df41d955efce6778994fb455d42d58
DIFF: https://github.com/llvm/llvm-project/commit/9145bf13b7df41d955efce6778994fb455d42d58.diff
LOG: [libc] Add example programs and their CMake build and instructions.
These examples are serve as an examples for people wanting to start
using the libc.
Reviewed By: michaelrj, jeffbailey
Differential Revision: https://reviews.llvm.org/D137090
Added:
libc/examples/examples.cmake
libc/examples/hello_world/.gitignore
libc/examples/hello_world/CMakeLists.txt
libc/examples/hello_world/hello_world.c
Modified:
libc/examples/README.md
Removed:
################################################################################
diff --git a/libc/examples/README.md b/libc/examples/README.md
index ecdbe33656939..5d6cb9489ae66 100644
--- a/libc/examples/README.md
+++ b/libc/examples/README.md
@@ -1 +1,79 @@
-Coming soon, stay tuned!
+Examples
+========
+This directory contains a few example programs which illustrate how one can set
+up their own projects to use LLVM's libc, either as an overlay or as the only
+libc in their projects. See the
+[the usage mode document](https://libc.llvm.org/usage_modes.html) for more
+information about the
diff erent modes in which one can build and use the libc.
+
+Building the Examples
+=====================
+Each example has its own directory which contain the source code and the CMake
+build set up. To build an example, create a directory named `build` in the
+example's directory:
+
+```bash
+$> cd <example directory>
+$> mkdir build
+$> cd build
+```
+
+Each example can be built to use the libc in either
+[the overlay mode](https://libc.llvm.org/overlay_mode.html) or the
+[full build mode](https://libc.llvm.org/fullbuild_mode.html). The CMake
+configure step
diff ers slightly depending on the mode you want to use the libc
+in.
+
+Building against an overlay libc
+--------------------------------
+
+Before you can link an example against the overlay libc, you will have to
+install it. See [the documentation of the overlay mode](https://libc.llvm.org/overlay_mode.html)
+to learn how to install the libc's overlay static archive named `libllvmlibc.a`.
+Once installed, to build an example against it, you have specify the directory
+in which the static archive is installed with the option
+`LIBC_OVERLAY_ARCHIVE_DIR`:
+
+```bash
+$> cmake ../ -G <GEN> \
+ -DLIBC_OVERLAY_ARCHIVE_DIR=<dir in which libc is installed>
+```
+
+Next, if `Ninja` is used for `<GEN>`, you can build the example as follows:
+
+```bash
+$> ninja <example name>
+```
+
+Building against a full libc
+----------------------------
+
+Before you can link an example against the full libc, you will have to first
+install it. See [the documentation of the full build mode](https://libc.llvm.org/fullbuild_mode.html)
+to learn how to install a full libc along with the other LLVM toolchain pieces
+like `clang`, `lld` and `compiler-rt`. The CMake build for the examples will
+assume that you have all of these components installed in a special sysroot
+(see decription of the `--sysroot` option
+[here](https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html).) Once you
+have installed them, you have to inform CMake that we are linking against the
+full libc as follows:
+
+```bash
+$> cmake ../ -G <GEN> -DLIBC_FULLBUILD=ON \
+ -DCMAKE_SYSROOT=<SYSROOT> \
+ -DCMAKE_C_COMPILER=<SYSROOT>/bin/clang \
+ -DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY
+```
+
+`<SYSROOT>` is the path to the sysroot directory you have set up while
+installing the full libc. The option
+`-DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY` tells CMake to not attempt
+linking full executables against shared libraries. We have to use this as LLVM's
+libc does not yet have support for shared libraries and dynamic linking. After
+the above `cmake` command, assuming `Ninja` was used for `<GEN>`, you can build
+the example as follows:
+
+
+```bash
+$> ninja <example name>
+```
diff --git a/libc/examples/examples.cmake b/libc/examples/examples.cmake
new file mode 100644
index 0000000000000..81e99e3cbede9
--- /dev/null
+++ b/libc/examples/examples.cmake
@@ -0,0 +1,16 @@
+function(add_example name)
+ add_executable(
+ ${name}
+ ${ARGN}
+ )
+
+ if(LIBC_FULLBUILD)
+ target_link_options(${name} PRIVATE -static -rtlib=compiler-rt -fuse-ld=lld)
+ elseif(LIBC_OVERLAY_ARCHIVE_DIR)
+ target_link_directories(${name} PRIVATE ${LIBC_OVERLAY_ARCHIVE_DIR})
+ target_link_options(${name} PRIVATE -l:libllvmlibc.a)
+ else()
+ message(FATAL_ERROR "Either LIBC_FULLBUILD should be on or "
+ "LIBC_OVERLAY_ARCHIVE_DIR should be set.")
+ endif()
+endfunction()
diff --git a/libc/examples/hello_world/.gitignore b/libc/examples/hello_world/.gitignore
new file mode 100644
index 0000000000000..0bda4771f3297
--- /dev/null
+++ b/libc/examples/hello_world/.gitignore
@@ -0,0 +1,10 @@
+#==============================================================================#
+# This file specifies intentionally untracked files that git should ignore.
+# See: http://www.kernel.org/pub/software/scm/git/docs/gitignore.html
+#
+# This file is intentionally
diff erent from the output of `git svn show-ignore`,
+# as most of those are useless.
+#==============================================================================#
+
+# Nested build directory
+/build*
diff --git a/libc/examples/hello_world/CMakeLists.txt b/libc/examples/hello_world/CMakeLists.txt
new file mode 100644
index 0000000000000..89bf35c0340d0
--- /dev/null
+++ b/libc/examples/hello_world/CMakeLists.txt
@@ -0,0 +1,8 @@
+project(hello_world)
+cmake_minimum_required(VERSION 3.13.4)
+include(../examples.cmake)
+
+add_example(
+ hello_world
+ hello_world.c
+)
diff --git a/libc/examples/hello_world/hello_world.c b/libc/examples/hello_world/hello_world.c
new file mode 100644
index 0000000000000..d065bdbb5a5bf
--- /dev/null
+++ b/libc/examples/hello_world/hello_world.c
@@ -0,0 +1,14 @@
+//===-- libc example - hello world ----------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include <stdio.h>
+
+int main() {
+ printf("Hello, World\n");
+ return 0;
+}
More information about the libc-commits
mailing list