Allow qpdf to be built on systems without wchar_t (fixes #406)

ChangeLog

@@ -1,5 +1,11 @@
 2020-04-03  Jay Berkenbilt  <ejb@ql.org>
 
+	* Allow qpdf to be built on systems without wchar_t. All "normal"
+	systems have wchar_t because it is part of the C++ standard, but
+	there are some stripped down environments that don't have it. See
+	README.md (search for wchar_t) for instructions and a discussion.
+	Fixes #406.
+
 	* Add two extra optional arguments to
 	QPDFPageObjectHelper::placeFormXObject to control whether the
 	placed item is allowed to be shrunk or expanded to fit within or

README.md

@@ -75,6 +75,20 @@ make install
 
 Packagers may set DESTDIR, in which case make install will install inside of DESTDIR, as is customary with many packages.  For more detailed general information, see the "INSTALL" file in this directory.  If you are already accustomed to building and installing software that uses autoconf, there's nothing new for you in the INSTALL file. Note that qpdf uses `autoconf` but not `automake`. We have our own system of Makefiles that allows cross-directory dependencies, doesn't use recursive make, and works better on non-UNIX platforms.
 
+# Building without wchar_t
+
+Executive summary: manually define -DQPDF_NO_WCHAR_T in your build if you are building on a system without wchar_t. For details, read the rest of this section.
+
+While wchar_t is part of the C++ standard library and should be present on virtually every system, there are some stripped down systems, such as those targetting certain embedded environments, that lack wchar_t. Internally, qpdf uses UTF-8 encoding for everything, so there is nothing important in qpdf's API that uses wchar_t. However, there is a helper method for converting between wchar_t* and char* that uses wchar_t.
+
+If you are building in an environment that does not support wchar_t, you can define the preprocessor symbol QPDF_NO_WCHAR_T in your build. This will work whether you are building qpdf and need to avoid compiling the code that uses wchar_t or whether you are building client code that uses qpdf.
+
+For example, to build qpdf on a system without wchar_t, be sure that -DQPDF_NO_WCHAR_T is part of your CXXFLAGS. Similar techniques will work in other places.
+
+Note that, when you build code with libqpdf, it is *not necessary* to have the definition of QPDF_NO_WCHAR_T in your build match what was defined when the library was built as long as you are not calling QUtil::call_main_from_wmain in your code. In other words, if your qpdf library was built on a system without wchar_t and you are using that system to build at some later time after wchar_t was available, as long as you don't call the function that uses it, you can just build normally.
+
+Note that QPDF_NO_WCHAR_T is never defined by autoconf or any other automated method. There is a hard rule in qpdf that values determined by autoconf are not available in the public API. This is because there is never a guarantee or even expectation that those values will match between the system on which qpdf was build and the system on which a user is building code with libqpdf.
+
 # Building on Windows
 
 QPDF is known to build and pass its test suite with mingw (latest version tested: gcc 7.2.0), mingw64 (latest version tested: 7.2.0) and Microsoft Visual C++ 2015, both 32-bit and 64-bit versions.  MSYS2 is required to build as well in order to get make and other related tools.  See [README-windows.md](README-windows.md) for details on how to build under Windows.

include/qpdf/QUtil.hh

@@ -357,12 +357,20 @@ namespace QUtil
     QPDF_DLL
     std::vector<int> parse_numrange(char const* range, int max);
 
+#ifndef QPDF_NO_WCHAR_T
+    // If you are building qpdf on a stripped down system that doesn't
+    // have wchar_t, such as may be the case in some embedded
+    // environments, you may define QPDF_NO_WCHAR_T in your build.
+    // This symbol is never defined automatically. Search for wchar_t
+    // in qpdf's top-level README.md file for details.
+
     // Take an argv array consisting of wchar_t, as when wmain is
     // invoked, convert all UTF-16 encoded strings to UTF-8, and call
     // another main.
     QPDF_DLL
     int call_main_from_wmain(int argc, wchar_t* argv[],
                              std::function<int(int, char*[])> realmain);
+#endif // QPDF_NO_WCHAR_T
 };
 
 #endif // QUTIL_HH

libqpdf/QUtil.cc

@@ -2342,8 +2342,10 @@ QUtil::possible_repaired_encodings(std::string supplied)
     return t;
 }
 
+#ifndef QPDF_NO_WCHAR_T
 int
-QUtil::call_main_from_wmain(int argc, wchar_t* argv[], std::function<int(int, char*[])> realmain)
+QUtil::call_main_from_wmain(int argc, wchar_t* argv[],
+                            std::function<int(int, char*[])> realmain)
 {
     // argv contains UTF-16-encoded strings with a 16-bit wchar_t.
     // Convert this to UTF-8-encoded strings for compatibility with
@@ -2376,3 +2378,4 @@ QUtil::call_main_from_wmain(int argc, wchar_t* argv[], std::function<int(int, ch
     new_argv[argc] = 0;
     return realmain(argc, new_argv);
 }
+#endif // QPDF_NO_WCHAR_T

libtests/build.mk

@@ -13,6 +13,7 @@ BINS_libtests = \
 	input_source \
 	json \
 	lzw \
+	main_from_wmain \
 	matrix \
 	md5 \
 	numrange \

libtests/main_from_wmain.cc

@@ -0,0 +1,34 @@
+#include <qpdf/QUtil.hh>
+#include <iostream>
+
+#ifndef QPDF_NO_WCHAR_T
+void wmain_test()
+{
+    auto realmain = [](int argc, char* argv[]) {
+                        for (int i = 0; i < argc; ++i) {
+                            std::cout << argv[i] << std::endl;
+                        } return 0;
+                    };
+    wchar_t* argv[3];
+    argv[0] = const_cast<wchar_t*>(L"ascii");
+    argv[1] = const_cast<wchar_t*>(L"10 \xf7 2 = 5");
+    argv[2] = const_cast<wchar_t*>(L"qwww\xf7\x03c0");
+    QUtil::call_main_from_wmain(3, argv, realmain);
+}
+#endif // QPDF_NO_WCHAR_T
+
+int main(int argc, char* argv[])
+{
+#ifndef QPDF_NO_WCHAR_T
+    try
+    {
+	wmain_test();
+    }
+    catch (std::exception& e)
+    {
+	std::cout << "unexpected exception: " << e.what() << std::endl;
+    }
+#endif // QPDF_NO_WCHAR_T
+
+    return 0;
+}

libtests/qtest/qutil.test

@@ -15,4 +15,20 @@ $td->runtest("QUtil",
 	      $td->EXIT_STATUS => 0},
 	     $td->NORMALIZE_NEWLINES | $td->RM_WS_ONLY_LINES);
 
-$td->report(1);
+my $mfw = `main_from_wmain`;
+if ($mfw eq '')
+{
+    $td->runtest("skipping main_from_wmain",
+                 {$td->STRING => ""},
+                 {$td->STRING => ""})
+}
+else
+{
+    $td->runtest("main_from_wmain",
+                 {$td->COMMAND => "main_from_wmain"},
+                 {$td->FILE => "wmain.out",
+                      $td->EXIT_STATUS => 0},
+                 $td->NORMALIZE_NEWLINES | $td->RM_WS_ONLY_LINES);
+}
+
+$td->report(2);

libtests/qtest/qutil/qutil.out

@@ -105,7 +105,3 @@ rename file
 create file
 rename over existing
 delete file
----- wmain
-ascii
-10 ÷ 2 = 5
-qwww÷π

libtests/qtest/qutil/wmain.out

@@ -0,0 +1,3 @@
+ascii
+10 ÷ 2 = 5
+qwww÷π

libtests/qutil.cc

@@ -543,17 +543,6 @@ void rename_delete_test()
     assert_no_file("old\xcf\x80.~tmp");
 }
 
-void wmain_test()
-{
-    auto realmain = [](int argc, char* argv[]) {
-                        for (int i = 0; i < argc; ++i) { std::cout << argv[i] << std::endl; } return 0; };
-    wchar_t* argv[3];
-    argv[0] = const_cast<wchar_t*>(L"ascii");
-    argv[1] = const_cast<wchar_t*>(L"10 \xf7 2 = 5");
-    argv[2] = const_cast<wchar_t*>(L"qwww\xf7\x03c0");
-    QUtil::call_main_from_wmain(3, argv, realmain);
-}
-
 int main(int argc, char* argv[])
 {
     try
@@ -584,8 +573,6 @@ int main(int argc, char* argv[])
 	hex_encode_decode_test();
 	std::cout << "---- rename/delete" << std::endl;
 	rename_delete_test();
-	std::cout << "---- wmain" << std::endl;
-	wmain_test();
     }
     catch (std::exception& e)
     {

manual/qpdf-manual.xml

@@ -239,6 +239,16 @@ make
     Jian Ma.  This is also discussed in more detail in
     <filename>README-windows.md</filename>.
    </para>
+   <para>
+    While <type>wchar_t</type> is part of the C++ standard, qpdf uses
+    it in only one place in the public API, and it's just in a helper
+    function. It is possible to build qpdf on a system that doesn't
+    have <type>wchar_t</type>, and it's also possible to compile a
+    program that uses qpdf on a system without <type>wchar_t</type> as
+    long as you don't call that one method. This is a very unusual
+    situation. For a detailed discussion, please see the top-level
+    README.md file in qpdf's source distribution.
+   </para>
    <para>
     There are some other things you can do with the build.  Although
     qpdf uses <application>autoconf</application>, it does not use