docs/cookbook/redoconf-simple: a simple redoconf C++ project.

This is a little simpler than the docs/cookbook/c project, which
doesn't actually have a doc yet because there was too much to explain.
I think I might make that a follow-on cookbook chapter, for people who
have read this simple one.

I think this doc is maybe a little too long; I intended it to be
"here's what you do to get started" but it turned into "here's what you
do to get started, and why it works, in excruciating detail." Not quite
sure how to fix.

(Also updated some other parts of the docs to refer to redoconf as a
real thing now instead of a "maybe someone should write this" thing.)

docs/Contributing.md

@@ -17,7 +17,7 @@ have a copy of redo.
 
 Nowadays, redo is good enough for real production use, and some people
 are using it for real work.  That said, it has
-not reached version 1.0 and there are surely still bugs.
+not reached version 1.0 and there are always going to be bugs.
 
 If you run into a problem, it's really helpful if you report it to the
 mailing list below (with or without subscribing first).  We really want to
@@ -29,21 +29,21 @@ Small feature additions are also welcome, but you might want to ask on the
 mailing list before you start working on it.  The code is still evolving and
 might not be the same by the time you submit your pull request.
 
-The best things you can do for redo are:
+Contributions to [redoconf](/cookbook/redoconf-simple/) are very welcome.
+For example, you might want to contribute detectors for new libraries or
+compilers.
+
+Some of the best things you can do for redo are:
 
 - Convert your projects to using it.  Without users, no project is
   successful.
 
-- Build new infrastructure around redo, especially things to make it easier
-  for people to get started.  For example, an automake-like tool that filled
-  in default redo build rules for common program types would probably be
-  very popular.
-
 - Convince your favourite OS distro to build and include (up to date!) redo
-  packages.
+  packages.  We especially need someone to help with getting redo included
+  in debian.
 
 - Help proofreading this documentation, and send patches or pull requests
-  with improvements.
+  with improvements and additions.
 
 - Join the mailing list (below) to discuss design changes or bugs.
 
@@ -52,7 +52,7 @@ The best things you can do for redo are:
 
 # Mailing list
 
-You should join the `[email protected]` mailing list.
+You should join the `[email protected]` mailing list!
 
 You can find the mailing list archives here:
 <http://groups.google.com/group/redo-list>

docs/FAQBasics.md

@@ -35,16 +35,11 @@ specific to ruby programs, or python programs, or Java or .Net programs.
 redo isn't like those systems; it's more like make.  It doesn't know
 anything about your system or the language your program is written in.
 
-The good news is: redo will work with *any* programming language with about
-equal difficulty.  The bad news is: you might have to fill in more details
-than you would if you just use ANT to compile a Java program.
-
-So the short version is: cross-platform builds are about equally easy in
-make and redo.  It's not any easier, but it's not any harder.
-
-It would be possible to make an automake-like or cmake-like tool that
-generates .do files for your project, just like automake generates
-Makefiles.  But that's beyond the scope of redo itself.
+However, there is a new project called [redoconf](/cookbook/redoconf-simple/)
+which is now part of the redo distribution.  It works kind of like
+`autoconf` does with make; drop it into your project and it will help with
+auto-detection, cross-compiling, and portability, so you can concentrate on
+actually writing your program.
 
 
 # Can I set my dircolors to highlight .do files in ls output?

docs/FAQInterop.md

@@ -1,13 +1,17 @@
 # Is redo compatible with autoconf?
 
-Yes.  You don't have to do anything special, other than the above note about
-declaring dependencies on config.h, which is no worse than what you would
-have to do with make.
+Yes.  You don't have to do anything special, other than making sure you
+`redo-ifchange config.h` (where `config.h` is generated by autoconf) in
+whatever redo script you use to compile your object files.  This
+is about the same as what you would have to do with make.
 
 
 # Is redo compatible with automake?
 
-Hells no.  You can thank me later.  But see next question.
+Not exactly; there is no point in generating Makefiles if you aren't going
+to use make.  However, we now include a similar project,
+[redoconf](/cookbook/redoconf-simple/), which provides a lot of the same
+features in a redo project that automake provides for a make project.
 
 
 # Is redo compatible with make?
@@ -22,7 +26,7 @@ In a file called myproject.stamp.do:
 	make -C myproject all
 
 So, to amend our answer to the previous question, you *can* use
-automake-generated Makefiles as part of your redo-based project.
+automake-generated Makefiles as part of your hybrid redo/make-based project.
 
 
 # Is redo -j compatible with make -j?

docs/Roadmap.md

@@ -309,21 +309,3 @@ consider bundling redo with a particular (optional) sh implementation, and
 maybe also unix-like tools, that it will use by default.  An obvious
 candidate would be busybox, which has a win32 version called
 [busybox-w32](https://frippery.org/busybox/).
-
-
-### redoconf
-
-redo is fundamentally a low-level tool that doesn't know as much about
-compiling specific programming languages as do higher-level tools like
-[cmake](https://cmake.org/).
-
-Similarly, `make` doesn't know much about specific programming languages
-(and what it does know is hopelessly out of date, but cannot be deleted or
-updated because it would break backward compatibility with old Makefiles).
-This is why `autoconf` and `automake` were created: to automatically fill in
-the language- and platform-specific blanks, while letting `make` still
-handle executing the low level instructions.
-
-It might be useful to have a redo-native autoconf/automake-like system,
-although you can already use autoconf with redo, so this might not be
-essential.

docs/cookbook/redoconf-simple/.gitignore

@@ -0,0 +1,2 @@
+/out
+/out.*

docs/cookbook/redoconf-simple/all.do

@@ -0,0 +1,15 @@
+# Run from the source dir.
+#
+# We'll make sure the out/ dir exists and that
+# a C++ compiler is available, then redo out/all,
+# which is implemented in the file all.od.
+#
+# Note that a "normal" project might not have an all.do
+# at all; the end user would be expected to make an
+# output dir, run ../configure, and then redo from there.
+# But we want this file to build as part of the redo
+# examples, so there needs to be a toplevel all.do in
+# each example.
+#
+. ./skip-if-no-cxx.sh
+redo-ifchange out/all

docs/cookbook/redoconf-simple/all.hpp

@@ -0,0 +1,11 @@
+// Precompiled header.
+//
+// Include your most commonly used, but least
+// frequently changing, header files here, to
+// speed up compilation.
+#ifndef __ALL_HPP
+
+#include <string>
+#include <iostream>
+
+#endif // __ALL_HPP

docs/cookbook/redoconf-simple/all.od

@@ -0,0 +1,3 @@
+# This script gets called from inside the out/
+# directory when someone runs "redo" or "redo all".
+redo-ifchange hello

docs/cookbook/redoconf-simple/all.rc.od

@@ -0,0 +1,34 @@
+# Specify which redoconf modules to use when building
+# our program.
+#
+# The rc_include function is available in every *.od
+# script in a redoconf project.
+rc_include \
+	rc/CXX.required.rc \
+	rc/Wextra.rc \
+	rc/all.hpp.precompiled.rc \
+	rc/openssl__ssl.h.rc \
+	rc/openssl__opensslv.h.rc \
+	rc/libssl.rc \
+	rc/libm.rc
+
+# We'll link *all* our binaries with the detected
+# $LIBSSL by default. We rc_included rc/libssl.rc
+# instead of rc/libssl.required.rc, so if it's
+# not available, this line won't add any
+# libraries. It'll be up to the program to check
+# for HAVE_LIBSSL before trying to call it.
+#
+# If we wanted to only link $LIBSSL into certain
+# binaries, we would include $LIBSSL explicitly in
+# the .list.od file for those binaries.  Since we're
+# putting it here, it doesn't have to be in the .list
+# file.
+rc_appendln LIBS "$LIBSSL"
+
+# Combine all the redoconf settings we've collected
+# above, and write them to $3 (all.rc). all.rc is
+# a special .rc file that is used when generating
+# the automatic ./compile and ./link scripts, among
+# others.
+rc_save

docs/cookbook/redoconf-simple/clean.do

@@ -0,0 +1,2 @@
+rm -f *~ .*~
+rm -rf out out.*

docs/cookbook/redoconf-simple/configure

@@ -0,0 +1,3 @@
+#!/bin/sh
+S="$(dirname "$0")"
+. "$S/redoconf/configure.sh"

docs/cookbook/redoconf-simple/configure.help

@@ -0,0 +1,15 @@
+# Automatically generated by redoconf/_all.rc.od - do not edit
+ARCH         Architecture prefix for output (eg. i686-w64-mingw32-)
+CC           C compiler name (cc)
+CPPFLAGS     Extra C preprocessor flags (eg. -I... -D...)
+CFLAGS       Extra C compiler flags (eg. -O2 -g)
+OPTFLAGS     C/C++ compiler flag overrides (eg. -g0)
+LINK         Linker name (cc)
+LDFLAGS      Extra linker options (eg. -s -static)
+LIBS         Extra libraries to always link against (eg. -lsocket)
+STATIC       Link libraries and binaries statically
+LIBSSL       Extra linker options for 'libssl libcrypto'
+LIBM         Extra linker options for 'libm'
+CXX          C++ compiler name (c++)
+CXXFLAGS     Extra C++ compiler flags (eg. -O2 -g)
+PREFIX       Change installation prefix (usually /usr/local)

docs/cookbook/redoconf-simple/configured.do

@@ -0,0 +1,9 @@
+# Ensure that an out/ directory exists and that
+# it has been configured (ie. ../configure has been run).
+[ -d out ] || (mkdir out && cd out && ../configure)
+
+# By declaring a dependency on this file *after* running
+# configure, we can tell redo that reconfiguration is
+# needed if this file ever disappears (for example, if
+# the whole out/ directory disappears).
+redo-ifchange out/default.do

docs/cookbook/redoconf-simple/hello.cc

@@ -0,0 +1,13 @@
+#include "all.hpp"
+#include "ssltest.h"
+
+using namespace std;
+
+int main() {
+	cout << "Hello, world!"
+	     << endl
+	     << "libssl version " 
+	     << hex << libssl_version()
+	     << endl;
+	return 0;
+}

docs/cookbook/redoconf-simple/hello.list.od

@@ -0,0 +1,14 @@
+rc_include all.rc
+
+# We include $LIBM here just as example of how to
+# specify an auto-detected library as part of the
+# linker settings for a binary.  We don't actually
+# use it for anything.  Note that $LIBM was detected
+# up above in the rc_include, because all.rc depends
+# on rc/libm.rc. If the library is not available,
+# $LIBM will be blank.
+cat <<-EOF
+	hello.cc
+	ssltest.c
+	$LIBM
+EOF