From 8aeae026d112ff9811a424e31621c05682f4a72e Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Tue, 18 Apr 2023 09:23:24 +0200
Subject: Add support for Assembler with C Preprocessor (.S) compilation

Specifically, the c module now provides the c.as-cpp submodules which can be
loaded in order to register the S{} target type and enable Assembler with C
Preprocessor compilation in the c compile rule. For details, refer to
"Assembler with C Preprocessor Compilation" in the manual.
---
 doc/manual.cli | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index 7f6b730..6f3def4 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -7329,6 +7329,90 @@ automatically link any necessary Objective-C runtime library (such as
 \c{-lobjc}).
 
 
+\h#c-as-cpp|Assembler with C Preprocessor Compilation|
+
+The \c{c} module provides the \c{c.as-cpp} submodules which can be loaded in
+order to register the \c{S{\}} target type and enable Assembler with C
+Preprocessor compilation in the \c{C} compile rule. Note that \c{c.as-cpp}
+must be loaded after the \c{c} module and while the \c{S{\}} target type is
+registered unconditionally, compilation is only enabled if the C compiler
+supports Assembler with C Preprocessor compilation.
+
+Typical usage:
+
+\
+# root.build
+#
+using c
+using c.as-cpp
+\
+
+\
+# buildfile
+#
+exe{hello}: {h c}{* -hello.c}
+
+# Use C implementation as a fallback if no assembler.
+#
+assembler = ($c.class == 'gcc' && $c.target.cpu == 'x86_64')
+
+exe{hello}: S{hello}: include = $assembler
+exe{hello}: c{hello}: include = (!$assembler)
+\
+
+\
+/* hello.S
+ */
+#ifndef HELLO_RESULT
+#  define HELLO_RESULT 0
+#endif
+
+text
+
+.global hello
+hello:
+  /* ... */
+  movq $HELLO_RESULT, %rax
+  ret
+
+#ifdef __ELF__
+.section .note.GNU-stack, \"\", @progbits
+#endif
+\
+
+The default file extension for the \c{S{\}} target type is \c{.S} (capital)
+but that can be customized using the standard mechanisms. For example:
+
+\
+# root.build
+#
+using c
+using c.as-cpp
+
+h{*}: extension = h
+c{*}: extension = c
+S{*}: extension = sx
+\
+
+Note that \c{*.coptions} are passed to the C compiler when compiling Assembler
+with C Preprocessor files because compile options may cause additional
+preprocessor macros to be defined. Plus, some of them (such as \c{-g}) are
+passed (potentially translated) to the underlying assembler. To pass
+additional options when compiling Assembler files use \c{c.poptions} and
+\c{c.coptions}. For example (continuing with the previous example):
+
+\
+if $assembler
+{
+  obj{hello}:
+  {
+    c.poptions += -DHELLO_RESULT=1
+    c.coptions += -Wa,--no-pad-sections
+  }
+}
+\
+
+
 \h1#module-cxx|\c{cxx} Module|
 
 \N{This chapter is a work in progress and is incomplete.}
-- 
cgit v1.1