Merge branch 'ticket_277' into 'main'

More documentation about refining build process and getting help

Closes #277

See merge request tpo/core/arti!259

CONTRIBUTING.md

@@ -74,11 +74,16 @@ link to your forked arti repository at:
     $ git remote add _name_ git@gitlab.torproject.org:_name_/arti.git
     $ git fetch _name_
 
-> Tip, replace `_name_` in above, and following, commands to reflect your sign
+> *Tip*: replace `_name_` in above, and following, commands to reflect your sign
 > in name.
 >
-> Note, to fork this repository, or contribute to Issues and Merge Requests
-> requires an account. Check the
+> *Note*: to fork this repository, or contribute to Issues and Merge Requests,
+> you will need an account on our gitlab server.  If you don't have an
+> account there, you can either
+> [request an account](https://gitlab.onionize.space/) or
+> [report a bug anonymously](https://anonticket.onionize.space/).
+>
+> Check the
 > [Sign In](https://gitlab.torproject.org/users/sign_in?redirect_to_referer=yes)
 > page for further instructions on requesting access.
 

README.md

@@ -75,6 +75,9 @@ SOCKS proxy on port 9150.
 Again, do not use this program yet if you seriously need anonymity, privacy,
 security, or stability.
 
+If you run into any trouble building the program, please have a
+look at [the troubleshooting guide](doc/TROUBLESHOOTING.md).
+
 ## Minimum supported Rust Version
 
 Our current Minimum Supported Rust Version (MSRV) is 1.53.
@@ -144,6 +147,14 @@ get our project manager to sign off on them.
 
  * Arti ?.?.?: Relay support
 
+## <a name="reporting-bugs"></a> How can I report bugs?
+
+When you find bugs, please report them
+[on our bugtracker](https://gitlab.torproject.org/tpo/core/arti/). If you
+don't already have an account there, you can either
+[request an account](https://gitlab.onionize.space/) or
+[report a bug anonymously](https://anonticket.onionize.space/).
+
 ## How can I help out?
 
 See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for a few ideas for how to get

doc/TROUBLESHOOTING.md

@@ -1,7 +1,10 @@
 # Fixing some common (and not-so-common) problems
 
 Here's an infrequently-asked-questions list about fixing some common (and
-not-so-common) issues in your Arti compilation or usage
+not-so-common) issues in your Arti compilation or usage.
+
+If you run into a problem that isn't on this list, please let us know on
+[our bugtracker](../README.md#reporting-bugs).
 
 ## Compilation issues
 
@@ -10,6 +13,30 @@ not-so-common) issues in your Arti compilation or usage
 Arti uses your system's sqlite3 and TLS libraries. Make sure that you have
 development libraries for sqlite3 installed.  You might also need to install
 the development libraries for OpenSSL, if you aren't on Windows or OSX.
+You may also need to install `pkg-config`.
+
+#### In more detail...
+
+We use sqlite3 via the `rusqlite` crate.  Our TLS implementation is the
+`native_tls` crate, which relies on `security-framework` (on OSX),
+`schannel` (on Windows), or `openssl` (elsewhere).
+
+Both of these crates, by default, access their dependencies via
+`pkg-config` or `vpkg` as appropriate.  But you can override this
+behavior if you run into trouble:
+
+  * You can build `arti` or `arti-client` with the `static` feature, and
+    the underlying crates will be told to build their own dependencies
+    from source and link statically.
+
+  * For more information on building `rusqlite` in different
+    environments, see [this section of their README](https://github.com/rusqlite/rusqlite#notes-on-building-rusqlite-and-libsqlite3-sys).
+
+  * For more information on building the `openssl` crate in different
+    environments, see the
+    ["building" section](https://docs.rs/openssl/latest/openssl/#building)
+    of their documentation.
+
 
 ### I get a weird segfault on startup on Alpine Linux!