[libc] Add example programs and their CMake build and instructions.

[sivachandra]

Summary

These examples are serve as an examples for people wanting to start
using the libc.

[jeffbailey]

I'm not sure that the repeated description of sysroot is necessary, but I'm not sure that it's not. I always worry about duplicated info.

libc/examples/README.md

4

"a few" means about three.
"few" means very little, and is often used in a negative context.

16

+.. code-block:: sh ? (Here and below)

17

Newline?

17

What does this comment mean?

32

s,this,the documentation on the overlay,

33

Part of me wishes that the library were called liblvmlibc.a so that the command line argument was -llvmlibc, similar to libiberty.

42

I wouldn't do multiple choice here. Pick one path to show it and stick with that, and I'd stick with whatever the default one is for LLVM is possible. If someone doesn't know what generators are supported and how they work, this isn't the place to learn about them.

You might make a note "We test with Makefile and Ninja generators here, but are showing $GENERATOR here for simplicity"

81

s,a ,,

81–82

s,and loading,,

[sivachandra]

Address comments.

libc/examples/README.md

16

I think the the .. code-block:: syntax is for .rst files? This is a .md file to be rendered like the README.md file here: https://github.com/llvm/llvm-project/tree/main/libc/src/__support/CPP. The idea is that this is a less formal document as opposed to the docs in the docs directory which are of a formal nature. I am calling it "less formal" to imply that this will have much more churn than the docs in the docs directory.

17

Removed it now.

33

Hmm ... the name is now hard coded in a few places upstream and downstream!

42

I have removed all discussion about the two types of generators.

[michaelrj]

LGTM

[jeffbailey]

I'm marking this as accepted - only the language annotation on the code blocks remains, but I think you'll have to just try something and see how the github MD interpreter copes with it. Thanks!

libc/examples/README.md

16

Ah! I hadn't realized that this isn't an rst file.

So, looking at: https://github.github.com/gfm/#info-string and https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code it looks like it's possible to do:

,,,bash (where those are backticks rather than commas, but this box is interpreting the MD if I use actual backticks)

However, I have no idea how to test this before committing it =)

I'm also not sure if you have to remove the "$> " as well.

[sivachandra]

Add bash as the language for code blocks.

[sivachandra]

libc/examples/README.md

16

I added bash as you suggested and removed the $>: https://github.com/llvm/llvm-project/tree/main/libc/examples

libc/examples/README.md

+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 different 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:
+
+```
+$> 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 differs 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`:
+
+```
+$> 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:
+
+```
+$> 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:
+
+```
+$> 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:
+
+
+```
+$> ninja <example name>
+```

libc/examples/examples.cmake

+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()

libc/examples/hello_world/.gitignore

+#==============================================================================#
+# 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 different from the output of `git svn show-ignore`,
+# as most of those are useless.
+#==============================================================================#
+
+# Nested build directory
+/build*

libc/examples/hello_world/CMakeLists.txt

+project(hello_world)
+cmake_minimum_required(VERSION 3.13.4)
+include(../examples.cmake)
+
+add_example(
+  hello_world
+  hello_world.c
+)

libc/examples/hello_world/hello_world.c

+//===-- 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;
+}