From 927a255e6c4abb34bf797f120c7a5186b7f113b7 Mon Sep 17 00:00:00 2001
From: Leo Butler <leo.butler@umanitoba.ca>
Date: Wed, 20 Dec 2023 12:06:13 -0600
Subject: [PATCH] ob-doc-C.org: document compile-only header

* org-contrib/babel/languages/ob-doc-C.org: Add :compile-only to the
list of header arguments.  Add a subsection, Compiling to a named
binary, that describes its use.

Ref:
https://list.orgmode.org/orgmode/87h6kdyh52.fsf_-_@t14.reltub.ca/T/#u
---
 org-contrib/babel/languages/ob-doc-C.org | 114 +++++++++++++++++++++++
 1 file changed, 114 insertions(+)

diff --git a/org-contrib/babel/languages/ob-doc-C.org b/org-contrib/babel/languages/ob-doc-C.org
index 14d83135..89f6e91f 100644
--- a/org-contrib/babel/languages/ob-doc-C.org
+++ b/org-contrib/babel/languages/ob-doc-C.org
@@ -69,6 +69,31 @@ the results of evaluation inserted into the buffer.
 : #+results:
 : : 2
 
+With C and C++, =ob-C.el= can also compile code to a named binary.
+
+#+name: c++-compile-only.org
+#+begin_src org :exports code :results replace
+,#+name: c++-compile-only
+,#+header: :file ./hello-world
+,#+header: :results file
+,#+header:  :includes <iostream>
+,#+begin_src C++
+std::cout << "Hello World++\n";
+,#+end_src
+#+end_src
+
+#+RESULTS: c++-compile-only.org
+#+name: c++-compile-only
+#+header: :file ./hello-world
+#+header: :results file
+#+header:  :includes <iostream>
+#+begin_src C++
+std::cout << "Hello World++\n";
+#+end_src
+
+: #+RESULTS: c++-compile-only
+: [[file:./hello-world]]
+
 ** About C
 C dates back to the 1970's.
 It was devised by Kernighan and Ritchie.
@@ -167,6 +192,10 @@ It features:
      (C & C++ only) useful for linking with a library, may be given
      =-L/path/to/lib= and =-llibrary= instructions.
 
+- =:compile-only= ::
+     (C & C++ only) compile the code block. The compiled binary is
+     /not/ executed; this file is named by the =:file= header argument.
+
 ** Sessions
    There is no support for sessions
 
@@ -256,6 +285,91 @@ When several libraries need to be included, =:includes= value should be set to a
 : Hello World!
 : 4
 
+** Compiling to a named binary
+:PROPERTIES:
+:ID:       0bf900ad-b1f3-4484-824b-cff84873e3d6
+:END:
+
+To compile source code to a dedicated binary, set the header argument
+~:compile-only~ to ~yes~. In this case, the binary file is /not/
+executed when the code block is evaluated. The results of the code
+block can also be inserted into the Org file.
+
+*** Compiling =hello-world=
+
+Set the ~:compile-only~ header argument to ~yes~ to produce the binary
+file =hello-world=. Note that an unset ~:file~ header argument throws
+an error.
+
+#+name: compile-only-insert-link.org
+#+begin_src org :exports code :results replace
+,#+name: compile-only-insert-link
+,#+header: :compile-only yes
+,#+header: :results file
+,#+header: :file ./hello-world
+,#+header: :includes <iostream>
+,#+begin_src C++
+std::cout << "Hello World!\n";
+,#+end_src
+#+end_src
+
+#+RESULTS: compile-only-insert-link.org
+#+name: compile-only-insert-link
+#+header: :compile-only yes
+#+header: :results file
+#+header: :file ./hello-world
+#+header: :includes <iostream>
+#+begin_src C++
+std::cout << "Hello World!\n";
+#+end_src
+
+With ~:results file~, evaluation of the code block inserts a link to
+the binary:
+
+: #+RESULTS: compile-only-insert-link
+: [[file:./hello-world]]
+
+*** Outputting compilation errors
+
+When ~:results output~ is set on the code block, compiler errors and
+warnings are inserted as results of the code block. In this example, a
+semi-colon is omitted, which throws a syntax error.
+
+#+name: compile-only-errors.org
+#+begin_src org :exports code :results replace
+,#+name: compile-only-errors
+,#+header: :compile-only yes
+,#+header: :results output
+,#+header: :file ./hello-world
+,#+header: :includes <iostream>
+,#+begin_src C++
+std::cout << "Hello World!\n"
+,#+end_src
+#+end_src
+
+#+RESULTS: compile-only-errors.org
+#+name: compile-only-errors
+#+header: :compile-only yes
+#+header: :results output
+#+header: :file ./hello-world
+#+header: :includes <iostream>
+#+begin_src C++
+std::cout << "Hello World!\n"
+#+end_src
+
+The result of evaluation of the code block is the compiler message
+(pathnames elided):
+
+#+RESULTS: compile-only-errors
+: ./hello-world.cpp: In function ‘int main()’:
+: ./hello-world.cpp:9:30: error: expected ‘;’ before ‘return’
+:     9 | std::cout << "Hello World!\n"
+:       |                              ^
+:       |                              ;
+:    10 | return 0;
+:       | ~~~~~~                        
+: [ Babel evaluation exited with code 1 ]
+
 ** Note that:
 - if no =main()= is declared, a trivial one is automatically provided,
 - there is no directive like:
-- 
2.42.0