Changes between Version 24 and Version 25 of BestPracticeHandbook

Timestamp:

May 15, 2015, 9:43:53 PM (7 years ago)

Author:

Niall Douglas

Comment:

--

BestPracticeHandbook

@@ -953 +953 @@
 The approaches for improving build times for your library users are generally as follows, and in order of effect:
 
- 1. Offer a non-header only build configuration:: Here is how many Boost libraries offer both header only and non-header only build configurations by using something like this in their config.hpp:
+'''1. Offer a non-header only build configuration'''
+
+ Non-header build configurations can offer build time improvements of x4 or more, so these are always the best bang for your buck. Here is how many Boost libraries offer both header only and non-header only build configurations by using something like this in their config.hpp:
 
  {{{#!c++
@@ -1007 +1009 @@
  This looks a bit complicated, but isn't really. Generally you will mark up those classes and structs you implement in a .ipp file (this being the file implementing the APIs declared in the header) with `BOOST_AFIO_DECL`, functions with `BOOST_AFIO_HEADERS_ONLY_FUNC_SPEC`, all out-of-class member functions (i.e. those not implemented inside the class or struct declaration) with `BOOST_AFIO_HEADERS_ONLY_MEMFUNC_SPEC`, all virtual member functions with `BOOST_AFIO_HEADERS_ONLY_VIRTUAL_SPEC` and append to all unimplemented virtual member functions  `BOOST_AFIO_HEADERS_ONLY_VIRTUAL_UNDEFINED_SPEC`. This inserts the correct markup to generate both optimal header only and optimal non header only outcomes.
 
- 2. Precompiled headers:: todo
-
- 3. extern template pre-instantiated copies of your templates with their most common template parameters into a separate static library:: todo
+'''2. Precompiled headers'''
+
+ You probably noticed that in the table above that precompiled headers gain nothing on clang, +13% on GCC and +70% on MSVC. Those percentages vary according to source code, but I have found them fairly similar across my own projects - on MSVC, precompiled headers are a must have on an already much faster compiler than any of the others.
+
+ Turning on precompiled headers in Boost.Build is easy:
+ {{{
+cpp-pch afio_pch : afio_pch.hpp : <include>. ;
+ }}}
+ And now simply link your program to afio_pch to enable. If you're on cmake, you definitely should check out https://github.com/sakra/cotire.
+
+'''3. `extern template` your templates with their most common template parameters in the headers, and force instantiate those same common instances into a separate static library'''
+
+ The following demonstrates the technique:
+ {{{#!c++
+// Header.hpp
+template<class T> struct Foo
+{
+  T v;
+  inline Foo(T _v);
+};
+// Definition must be made outside struct Foo for extern template to have effect
+template<class T> inline Foo<T>::Foo(T _v) : v(_v) { }
+
+// Inhibit automatic instantiation of struct Foo for common types
+extern template struct Foo<int>;
+extern template struct Foo<double>;
+
+
+// Source.cpp
+#include "Header.hpp"
+#include <stdio.h>
+
+// Force instantiation of struct Foo with common types. Usually compiled into
+// a separate static library as bundling it into the main shared library can
+// introduce symbol visibility problems, so it's easier and safer to use a static
+// library
+template struct Foo<int>;
+template struct Foo<double>;
+
+int main(void)
+{
+  Foo<long> a(5);   // Works!
+  Foo<int> b(5);    // Symbol not found if not force instantiated above
+  Foo<double> c(5); // Symbol not found if not force instantiated above
+  printf("a=%l, b=%d, c=%lf\n", a.v, b.v, c.v);
+  return 0;
+}
+ }}}
+ The idea behind this is to tell the compiler to not instantiate common instantiations of your template types on demand for every single compiland as you will explicitly instantiate them exactly once elsewhere. This can give quite a bump to build times for template heavy libraries.