From 083f5f3138adbb3d1dfa6065f4b925573e78fc70 Mon Sep 17 00:00:00 2001
From: Martin Habovstiak <martin.habovstiak@gmail.com>
Date: Mon, 20 Sep 2021 21:29:44 +0200
Subject: [PATCH] Document lack of support for 16-bit pointers

This clearly states lack of support for 16-bit architectures as well as
adds readable `compile_error!()` call. It also fixes a few stylistic
mistakes - headings (top-level should not be repeated) and missing
newlines.

Closes #660
---
 README.md  | 21 ++++++++++++++++-----
 src/lib.rs |  9 +++++++++
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index b3079f45..4729b6d1 100644
--- a/README.md
+++ b/README.md
@@ -20,9 +20,9 @@ Supports (or should support)
 For JSONRPC interaction with Bitcoin Core, it is recommended to use
 [rust-bitcoincore-rpc](https://github.com/rust-bitcoin/rust-bitcoincore-rpc).
 
-# Known limitations
+## Known limitations
 
-## Consensus
+### Consensus
 
 This library **must not** be used for consensus code (i.e. fully validating
 blockchain data). It technically supports doing this, but doing so is very
@@ -36,13 +36,20 @@ Given the complexity of both C++ and Rust, it is unlikely that this will
 ever be fixed, and there are no plans to do so. Of course, patches to
 fix specific consensus incompatibilities are welcome.
 
+### Support for 16-bit pointer sizes
+
+16-bit pointer sizes are not supported and we can't promise they will be.
+If you care about them please let us know, so we can know how large the interest
+is and possibly decide to support them.
+
 ## Documentation
 
 Currently can be found on [docs.rs/bitcoin](https://docs.rs/bitcoin/).
 Patches to add usage examples and to expand on existing docs would be extremely
 appreciated.
 
-# Contributing
+## Contributing
+
 Contributions are generally welcome. If you intend to make larger changes please
 discuss them in an issue before PRing them to avoid duplicate work and
 architectural mismatches. If you have any questions or ideas you want to discuss
@@ -51,6 +58,7 @@ please join us in
 [libera.chat](https://libera.chat).
 
 ## Minimum Supported Rust Version (MSRV)
+
 This library should always compile with any combination of features on **Rust 1.29**.
 
 Because some dependencies have broken the build in minor/patch releases, to
@@ -72,6 +80,7 @@ cargo update -p byteorder --precise "1.3.4"
 ```
 
 ## Installing Rust
+
 Rust can be installed using your package manager of choice or
 [rustup.rs](https://rustup.rs). The former way is considered more secure since
 it typically doesn't involve trust in the CA system. But you should be aware
@@ -80,6 +89,7 @@ Generally this isn't a problem for `rust-bitcoin` since we support much older
 versions than the current stable one (see MSRV section).
 
 ## Building
+
 The library can be built and tested using [`cargo`](https://github.com/rust-lang/cargo/):
 
 ```
@@ -97,6 +107,7 @@ cargo test
 Please refer to the [`cargo` documentation](https://doc.rust-lang.org/stable/cargo/) for more detailed instructions. 
 
 ## Pull Requests
+
 Every PR needs at least two reviews to get merged. During the review phase
 maintainers and contributors are likely to leave comments and request changes.
 Please try to address them, otherwise your PR might get closed without merging
@@ -117,12 +128,12 @@ cross-chain atomic swaps) are more likely to be accepted than things which
 support only a single blockchain.
 
 
-# Release Notes
+## Release Notes
 
 See [CHANGELOG.md](CHANGELOG.md).
 
 
-# Licensing
+## Licensing
 
 The code in this project is licensed under the [Creative Commons CC0 1.0
 Universal license](LICENSE).
diff --git a/src/lib.rs b/src/lib.rs
index c8c70849..e01ea17c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -22,6 +22,9 @@
 //! safety, including ownership and lifetime, for financial and/or cryptographic
 //! software.
 //!
+//! See README.md for detailed documentation about development and supported
+//! environments.
+//!
 //! ## Available feature flags
 //!
 //! * `std` - the usual dependency on `std` (default).
@@ -58,6 +61,12 @@
 #[cfg(not(any(feature = "std", feature = "no-std")))]
 compile_error!("at least one of the `std` or `no-std` features must be enabled");
 
+// Disable 16-bit support at least for now as we can't guarantee it yet.
+#[cfg(target_pointer_width = "16")]
+compile_error!("rust-bitcoin currently only supports architectures with pointers wider
+                than 16 bits, let us know if you want 16-bit support. Note that we do
+                NOT guarantee that we will implement it!");
+
 #[cfg(feature = "no-std")]
 #[macro_use]
 extern crate alloc;