PlatformsAndLibraries.md (26611B)
1 # Platform and library support for Trompeloeil 2 3 <!-- no toc --> 4 - [Using libc\+\+ with Trompeloeil](#using_libcxx) 5 - [Using sanitizers with Trompeloeil](#using_sanitizers) 6 - [Compiler versions in sample Linux distributions](#compilers_in_distributions) 7 - [Ubuntu](#compilers_in_ubuntu) 8 - [In summary](#ubuntu_summary) 9 - [In detail](#ubuntu_detail) 10 - [Fedora](#compilers_in_fedora) 11 - [Tested configurations](#tested_configurations) 12 - [Testing Trompeloeil on Artful Aardvark (Ubuntu 17.10)](#testing_on_artful) 13 - [`std::to_string()` is not defined for some versions of `libstdc++-v3`](#defect_to_string) 14 - [Glibc 2.26 no longer supplies `xlocale.h`](#defect_xlocale) 15 - [Glibc 2.26 `std::signbit()` broken for GCC compilers < 6](#defect_signbit) 16 - [Conclusion](#artful_conclusion) 17 - [Supporting incomplete standard libraries](#incomplete_stdlib) 18 - [Replacing `std::recursive_mutex`](#custom_recursive_mutex) 19 - [Replacing `std::atomic<T>`](#custom_std_atomic) 20 - [Replacing `std::unique_lock<T>`](#custom_std_unique_lock) 21 22 ## <A name="using_libcxx"/> Using libc\+\+ with Trompeloeil 23 24 On some distributions `clang` is configured to use `libstdc++-v3` as the 25 implementation of the C\+\+ Standard Library. In order to use `libc++`, 26 pass the `-stdlib=libc++` command line flag to the compiler. 27 28 For example, 29 30 ```text 31 clang++-5.0 -std=c++14 -stdlib=libc++ <other command line arguments> 32 ``` 33 34 To use `libc++` with `g++` a few more command line flags need to be passed. 35 This is a command line known to work with `g++-6`, 36 37 ```text 38 g++-6 -std=c++14 -nostdinc++ -isystem/usr/include/c++/v1 \ 39 <other command line arguments> \ 40 -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc 41 ``` 42 43 ## <A name="using_sanitizers"/> Using sanitizers with Trompeloeil 44 45 Trompeloeil test cases have been compiled and run without error with 46 AddressSanitizer (ASan), Undefined Behavior Sanitizer (UBSan) and 47 Thread Sanitizer (TSan). 48 49 Feel free to add `-fsanitize=address`, `-fsanitize=thread` or 50 `-fsanitize=undefined` to your compiler command lines, especially 51 when unit testing. 52 53 Maybe your compiler supports `-fsanitize-address-use-after-scope`. 54 Add that flag as well. 55 56 ## <A name="compilers_in_distributions"/> Compiler versions in sample Linux distributions 57 58 ### <A name="compilers_in_ubuntu"/> Ubuntu 59 60 Canonical supports the `main` component of the repositories of a release. 61 62 Canonical does not support the `universe` component. Support for `universe` 63 is provided by the Ubuntu community. If a compiler or library is in `universe` 64 for a particular release, then there is no guarantee that there will be a 65 release of that compiler or library in the next or any future release of 66 Ubuntu, let alone updates in the current release. 67 68 Either migrate compilers and libraries with each Ubuntu release or take 69 control of your toolchain and remove a dependency on the platform. In the 70 latter case you then have the option of supporting the Ubuntu community 71 with a contribution of your toolchain to `universe`. 72 73 For more information, see 74 75 ubuntu.com, "Repositories" \ 76 Available: <https://help.ubuntu.com/community/Repositories> \ 77 Accessed: 29 October 2017 78 79 #### <A name="ubuntu_summary"/> In summary 80 81 ```text 82 Trusty Tahr Xenial Xerus Zesty Zapus Artful Aardvark Bionic Beaver 83 (14.04LTS) (16.04LTS) (17.04) (17.10) (18.04LTS) 84 Released 2014-04-17 2016-04-21 2017-04-17 2017-10-19 2018-04 85 Supported to 2019-04 2021-04 2018-01 2018-07 2023-04 86 87 Compiler(s) g++-4.8.4 g++-5 g++-6 g++-7 TODO 88 89 clang++-3.5 clang++-4.0 clang++-4.0 universe TODO 90 clang++-5.0 TODO 91 92 93 libc++-dev universe universe universe universe TODO 94 1.0~svn199600-1 3.7.0 3.9.1 3.9.1 TODO 95 ``` 96 97 #### <A name="ubuntu_detail"/> In detail 98 99 ```text 100 Trusty Tahr Xenial Xerus Zesty Zapus Artful Aardvark Bionic Beaver 101 (14.04LTS) (16.04LTS) (17.04) (17.10) (18.04LTS) 102 Released 2014-04-17 2016-04-21 2017-04-17 2017-10-19 2018-04 103 Supported to (2019-04) (2021-04) (2018-01) (2018-07) (2023-04) 104 105 GCC 106 107 g++-4.8 ports universe universe universe TODO 108 4.8.2-19ubuntu1 4.8.5-4ubuntu2 4.8.5-4ubuntu4 4.8.5-4ubuntu6 TODO 109 110 security xenial-updates zesty-updates TODO 111 4.8.4-2ubuntu1~14.04.3 N/A N/A TODO 112 113 trusty-updates xenial-backports zesty-backports TODO 114 4.8.4-2ubuntu1~14.04.3 N/A N/A TODO 115 116 trusty-backports 117 N/A 118 119 120 g++-4.9 main universe universe universe TODO 121 N/A 4.9.3-13ubuntu2 4.9.4-2ubuntu1 N/A TODO 122 123 trusty-updates xenial-updates zesty-updates TODO 124 N/A N/A N/A TODO 125 126 trusty-backports xenial-backports zesty-backports TODO 127 N/A N/A N/A TODO 128 129 130 g++-5 main ports universe universe TODO 131 N/A 5.3.1-14ubuntu2 5.4.1-8ubuntu1 5.5.0-1ubuntu1 TODO 132 133 trusty-updates security zesty-updates TODO 134 N/A 5.4.0-6ubuntu1~16.04.4 N/A TODO 135 136 trusty-backports xenial-updates zesty-backports TODO 137 N/A 5.4.0-6ubuntu1~16.04.5 N/A TODO 138 139 xenial-backports 140 N/A 141 142 143 g++-6 main main ports universe TODO 144 N/A N/A 6.3.0-8ubuntu1 6.4.0-8ubuntu1 TODO 145 146 trusty-updates xenial-updates main TODO 147 N/A N/A 6.3.0-12ubuntu2 TODO 148 149 trusty-backports xenial-backports zesty-updates TODO 150 N/A N/A N/A TODO 151 152 zesty-backports 153 N/A 154 155 156 g++-7 main main main main TODO 157 N/A N/A N/A 7.2.0-8ubuntu3 TODO 158 159 trusty-updates xenial-updates xenial-updates TODO 160 N/A N/A N/A TODO 161 162 trusty-backports xenial-backports xenial-backports TODO 163 N/A N/A N/A TODO 164 165 166 Clang 167 168 clang-3.5 ports universe N/A N/A TODO 169 1:3.5~svn201651-1ubuntu1 1:3.5.2-3ubuntu1 N/A N/A TODO 170 171 security xenial-updates zesty-updates TODO 172 1:3.5-4ubuntu2~trusty2 N/A N/A TODO 173 174 trusty-updates xenial-backports zesty-backports TODO 175 1:3.5-4ubuntu2~trusty2 N/A N/A TODO 176 177 trusty-backports 178 N/A 179 180 181 clang-3.6 N/A universe N/A N/A TODO 182 N/A 1:3.6.2-3ubuntu2 N/A N/A TODO 183 184 trusty-updates/universe xenial-updates zesty-updates TODO 185 1:3.6-2ubuntu1~trusty1 N/A N/A TODO 186 187 trusty-backports xenial-backports zesty-backports TODO 188 N/A N/A N/A TODO 189 190 191 clang-3.7 N/A universe universe N/A TODO 192 N/A 1:3.7.1-2ubuntu2 1:3.7.1-3ubuntu4 N/A TODO 193 194 trusty-updates xenial-updates zesty-updates TODO 195 N/A N/A N/A TODO 196 197 trusty-backports xenial-backports zesty-backports TODO 198 N/A N/A N/A TODO 199 200 201 clang-3.8 security universe universe universe TODO 202 1:3.8-2ubuntu3~trusty5 1:3.8-2ubuntu1 1:3.8.1-18ubuntu1 1:3.8.1-24ubuntu7 TODO 203 204 trusty-updates/universe xenial-updates/universe zesty-updates TODO 205 1:3.8-2ubuntu3~trusty5 1:3.8-2ubuntu4 N/A TODO 206 207 trusty-backports xenial-backports zesty-backports TODO 208 N/A N/A N/A TODO 209 210 211 clang-3.9 security security ports universe TODO 212 1:3.9.1-4ubuntu3~14.04.3 1:3.9.1-4ubuntu3~16.04.2 1:3.9.1-5ubuntu1 1:3.9.1-17ubuntu1 TODO 213 214 trusty-updates/universe xenial-updates/universe security TODO 215 1:3.9.1-4ubuntu3~14.04.3 1:3.9.1-4ubuntu3~16.04.2 1:3.9.1-5ubuntu1.1 TODO 216 217 trusty-backports xenial-backports zesty-updates TODO 218 N/A N/A 1:3.9.1-5ubuntu1.1 TODO 219 220 zesty-backports TODO 221 N/A TODO 222 223 224 clang-4.0 N/A security main universe TODO 225 N/A 1:4.0-1ubuntu1~16.04.2 1:4.0-1ubuntu1 1:4.0.1-6 TODO 226 227 trusty-updates xenial-updates zesty-updates TODO 228 N/A 1:4.0-1ubuntu1~16.04.2 N/A TODO 229 230 trusty-backports xenial-backports zesty-backports TODO 231 N/A N/A N/A TODO 232 233 234 clang-5.0 N/A N/A N/A universe TODO 235 N/A N/A N/A 1:5.0-3 TODO 236 237 trusty-updates xenial-updates zesty-updates TODO 238 N/A N/A N/A TODO 239 240 trusty-backports xenial-backports zesty-backports TODO 241 N/A N/A N/A TODO 242 243 libc++-dev 244 245 1.0 universe 246 1.0~svn199600-1 247 248 trusty-updates 249 N/A 250 251 trusty-backports 252 N/A 253 254 3.7 universe 255 3.7.0-1 256 257 xenial-updates/universe 258 3.7.0-1ubuntu0.1 259 260 xenial-backports 261 N/A 262 263 3.9 ports universe 264 3.7.0-1 3.9.1-3 265 266 universe 267 3.9.1-2 268 269 zesty-updates 270 N/A 271 272 zesty-backports 273 N/A 274 275 4.0 TODO 276 TODO 277 278 279 5.0 TODO 280 TODO 281 ``` 282 283 Table first compiled: 28 October 2017. 284 Last updated: 28 October 2017. 285 286 ### <A name="compilers_in_fedora"/> Fedora 287 288 A short list of Fedora releases tells a similar story 289 to the Ubuntu distribution. 290 291 ```text 292 25 26 27 28 293 Released 2016-11-22 2017-07-11 (2017-11-14) (2018-05-01) 294 Supported to TODO TODO TBD TBD 295 296 gcc-c++ 6.4.1-1.fc25 7.2.1-2.fc26 7.2.1-2.fc27 TODO 297 g++ 6.4.1 20170727 7.2.1 20170915 7.2.1 20170915 TODO 298 (Red Hat 6.4.1-1) (Red Hat 7.2.1-2) (Red Hat 7.2.1-2) 299 300 301 clang 3.9.1-2.fc25 4.0.1-5.fc26 4.0.1-5.fc27 TODO 302 clang++ 3.9.1 4.0.1 4.0.1 TODO 303 (tags/RELEASE_391/final (tags/RELEASE_401/final) (tags/RELEASE_401/final) 304 305 306 libcxx-devel 3.9.1-1.fc25 4.0.1-3.fc26 4.0.1-3.fc27 TODO 307 ``` 308 309 Table first compiled: 28 October 2017 310 Last updated: 9 November 2017 311 312 ## <A name="tested_configurations"/> Tested configurations 313 314 Before release, Trompeloeil is tested with the following configurations 315 of compiler, language dialect, and standard library. 316 317 ### GCC 318 319 Last updated: 3 June 2019 320 321 Key: 322 323 - `N/A`: The combination `g++-4.8/c++11/libc++` leads to 324 compile errors and is not currently supported. Further investigation 325 may change this outcome. 326 - `--`: The version of `libstdc++-v3` lacks a definition of the 327 `_GLIBCXX_RELEASE` macro. 328 - `stdc++` means `libstdc++-v3` from GCC. 329 - `c++` means `libc++` from Clang. 330 331 `g++-latest` means the "live at head" build of `g++`. 332 333 ```text 334 Compiler Mode stdc++ c++ 335 -std= __GLIBCXX__ _GLIBCXX_RELEASE _LIBCPP_VERSION 336 ---------- ---- ------------------------------ --------------- 337 g++-4.8 c++11 20150623 -- N/A 338 339 340 g++-4.9 c++11 20160726 -- 8000 341 c++14 342 343 g++-5 c++11 20171010 -- 8000 344 c++14 345 c++17 346 347 g++-6 c++11 20181026 -- 8000 348 c++14 349 c++17 350 351 352 g++-7 c++11 20190326 7 8000 353 c++14 354 c++17 355 356 357 g++-8 c++11 20190406 8 8000 358 c++14 359 c++17 360 c++2a 361 362 363 g++-9 c++11 20190402 9 8000 364 c++14 365 c++17 366 c++2a 367 368 369 g++-latest c++11 20190421 9 8000 370 c++14 371 c++17 372 c++2a 373 ``` 374 375 ### Clang 376 377 `clang++-latest` means the "live at head" version of `clang++`. 378 379 ```text 380 Compiler Mode stdc++ c++ 381 -std= __GLIBCXX__ _GLIBCXX_RELEASE _LIBCPP_VERSION 382 ---------- ---- ------------------------------ --------------- 383 clang++-3.5 c++11 20190326 7 1101 384 c++14 385 386 387 clang++-3.6 c++11 20190326 7 1101 388 c++14 389 390 391 clang++-3.7 c++11 20190326 7 3700 392 c++14 393 394 395 clang++-3.8 c++11 20190326 7 3800 396 c++14 397 398 399 clang++-3.9 c++11 20190402 9 3900 400 c++14 401 402 403 clang++-4.0 c++11 20190402 9 4000 404 c++14 405 406 407 clang++-5.0 c++11 20190402 9 5000 408 c++14 409 c++17 410 c++2a 411 412 413 clang++-6.0 c++11 20190402 9 6000 414 c++14 415 c++17 416 c++2a 417 418 419 clang++-7 c++11 20190402 9 7000 420 c++14 421 c++17 422 c++2a 423 424 425 clang++-8 c++11 20190402 9 8000 426 c++14 427 c++17 428 c++2a 429 430 431 clang++-latest c++11 20190402 9 9000 432 c++14 433 c++17 434 c++2a 435 ``` 436 437 ### Microsoft Visual Studio 438 439 Last update: 3 June 2019 440 441 Tested with Visual Studio Community 2019 16.1.1 . 442 443 ```text 444 Platform Toolset Configuration Platform 445 ------------------------- ------------- -------- 446 Visual Studio 2015 (v140) Debug x64 447 Visual Studio 2017 (v141) Release x86 448 Visual Studio 2019 (v142) 449 ``` 450 451 ## <A name="testing_on_artful"/> Testing Trompeloeil on Artful Aardvark (Ubuntu 17.10) 452 453 The release of Artful Aardvark (Ubuntu 17.10) contains a number of issues 454 requiring workarounds if you want to compile and test Trompeloeil with 455 community supported compiler versions e.g. any version of `clang++`, 456 any version `g++` less than 7, or community supported libraries e.g. 457 any version of `libc++`. 458 459 Canonical supported compilers and libraries - 460 just `g++-7` with `libstdc++-v3` - do not have the issues described below, 461 but this is rather a narrow list for testing Trompeloeil on its 462 supported compilers and libraries. 463 464 ### <A name="defect_to_string"/> `std::to_string()` is not defined for some versions of `libstdc++-v3` 465 466 Affects: `libstdc++-v3` from these packages 467 468 - `libstdc++-4.8-dev:amd64 4.8.5-4ubuntu6` 469 - See: <https://bugs.launchpad.net/ubuntu/+source/gcc-4.8/+bug/1725847> 470 - `libstdc++-5-dev:amd64 5.5.0-1ubuntu1` 471 - See: <https://bugs.launchpad.net/ubuntu/+source/gcc-5/+bug/1725848> 472 473 Workaround: Add `-D_GLIBCXX_USE_C99=1` to your compiler command lines. 474 475 ### <A name="defect_xlocale"/> Glibc 2.26 no longer supplies `xlocale.h` 476 477 The version of `glibc` in package `libc6-dev (2.26-0ubuntu2)` 478 drops support for `xlocale.h`. 479 480 `libc++` tracked this change and supplied a fix for 5.0. 481 482 See: "Fix libcxx build with glibc 2.26+ by removing xlocale.h include." \ 483 Available: <https://github.com/llvm-mirror/libcxx/commit/6e02e89f65ca1ca1d6ce30fbc557563164dd327e> \ 484 Accessed: 11 November 2017 485 486 But Artful Aardvark ships package `libc++-dev 3.9.1-3`. 487 As a consequence, no software using `libc++` out-of-the-box version 488 can compile on Artful. 489 490 Workaround: Create a symlink from `locale.h` to `xlocale.h` 491 492 ```text 493 cd /usr/include 494 sudo ln -s locale.h xlocale.h 495 ``` 496 497 ### <A name="defect_signbit"/> Glibc 2.26 `std::signbit()` broken for GCC compilers < 6 498 499 A defect in GLIBC 2.26 prevents programs using `signbit()` from `math.h` 500 from compiling with `g++-4.8`, `g++-4.9`, or `g++-5`. 501 502 This happens to include any uses of `libc++`, which requires a 503 functioning `signbit()` to compile function template `__libcpp_signbit()` 504 in file `math.h`. 505 506 The Clang compilers happen to work with this part of `glibc` 2.26 507 as they don't implement 128-bit floating point and a different 508 code path is followed, even for the earliest supported compilers. 509 510 See: <https://bugs.launchpad.net/ubuntu/+source/glibc/+bug/1725869> 511 512 Workaround: Patch your local copy of `math.h` in `glibc` with the 513 fix from `glibc` upstream, found by following the links in this bug report: 514 515 See: "Bug 22296 - glibc 2.26: signbit build issue with Gcc 5.5.0 on x86_64" \ 516 Available: <https://sourceware.org/bugzilla/show_bug.cgi?id=22296> \ 517 Accessed: 11 November 2017 518 519 ### <A name="artful_conclusion"/> Conclusion 520 521 Hopefully updated packages for `glibc` (`libc6-dev`), `libc++`, and 522 `libstdc++-dev` for `g++-4.8` and `g++-5` will be released allowing 523 patch-free building and testing of Trompeloeil on Artful Aardvark. 524 525 A better strategy may be to build GLIBC, GCC 4.8, GCC 5.x, and `libc++` 526 from source and use these to build your software. Then consider 527 contributing your build to the Ubuntu Community; you just might be the 528 "support" in "community supported". 529 530 ## <A name="incomplete_stdlib"/> Supporting incomplete standard libraries 531 532 Some platforms, especially MCUs with RTOS, only have partial support for the 533 standard library `<atomic>` and `<mutex>` headers used by trompeloeil. 534 In many cases, it is possible to provide shims or custom implementations 535 of the necessary parts. 536 537 ### <A name="custom_recursive_mutex"/> Replacing `std::recursive_mutex` 538 539 To use your own recursive mutex, define `TROMPELOEIL_CUSTOM_RECURSIVE_MUTEX` 540 either before including the Trompeloeil header 541 (e.g. `#define TROMPELOEIL_CUSTOM_RECURSIVE_MUTEX`) or as preprocessor 542 definition (e.g. GCC: `-DTROMPELOEIL_CUSTOM_RECURSIVE_MUTEX`). 543 544 Now define in one translation unit your custom recursive mutex for trompeloeil. 545 546 ```cpp 547 namespace trompeloeil { 548 549 std::unique_ptr<custom_recursive_mutex> create_custom_recursive_mutex() { 550 551 class custom : public custom_recursive_mutex { 552 void lock() override { mtx.lock(); } 553 void unlock() override { mtx.unlock(); } 554 555 private: 556 mylib::recursive_mutex mtx; 557 }; 558 559 return std::make_unique<custom>(); 560 } 561 562 } 563 ``` 564 565 ### <A name="custom_std_atomic"/> Replacing `std::atomic<T>` 566 567 To use your own implementation of `std::atomic<T>`, 568 define `TROMPELOEIL_CUSTOM_ATOMIC` and make sure there is a header 569 `trompeloeil/custom_atomic.hpp` somewhere in the include search path. 570 571 This header should contain a class template `trompeloeil::atomic<T>` 572 that implements (part of) the interface of `std::atomic<T>`: 573 574 ```cpp 575 namespace trompeloeil 576 { 577 template <typename T> 578 class atomic 579 { 580 public: 581 atomic() : m_atomic() 582 { 583 } 584 585 explicit atomic(const T initial) : m_atomic(initial) 586 { 587 } 588 589 T operator=(T desired) 590 { 591 m_atomic.store(desired); 592 return m_atomic.load(); 593 } 594 595 operator T() const 596 { 597 return m_atomic.load(); 598 } 599 600 private: 601 mylib::atomic<T> m_atomic; 602 }; 603 } 604 ``` 605 606 ### <A name="custom_std_unique_lock"/> Replacing `std::unique_lock<T>` 607 608 To use your own implementation of `std::unique_lock<T>`, 609 define `TROMPELOEIL_CUSTOM_UNIQUE_LOCK` and make sure there is a header 610 `trompeloeil/custom_unique_lock.hpp` somewhere in the include search path. 611 612 This header should contain a class template `trompeloeil::unique_lock<T>` 613 that implements (part of) the interface of `std::unique_lock<T>`: 614 615 ```cpp 616 namespace trompeloeil 617 { 618 template <typename Mutex> 619 class unique_lock 620 { 621 public: 622 unique_lock() noexcept : m_mutex(nullptr) 623 { 624 } 625 626 explicit unique_lock(Mutex& mutex) : m_mutex(&mutex) 627 { 628 m_mutex->lock(); 629 } 630 631 unique_lock(const unique_lock&) = delete; 632 unique_lock(unique_lock&& other) noexcept : m_mutex(nullptr) 633 { 634 std::swap(other.m_mutex, m_mutex); 635 } 636 637 unique_lock& operator=(const unique_lock&) = delete; 638 unique_lock& operator=(unique_lock&& other) noexcept 639 { 640 std::swap(other.m_mutex, m_mutex); 641 } 642 643 ~unique_lock() 644 { 645 if (m_mutex) 646 { 647 m_mutex->unlock(); 648 } 649 } 650 651 private: 652 Mutex* m_mutex; 653 }; 654 } 655 ```