[Docs] Add general remarks about what to do when a build fails (#1088)

[skip azp]

Author: giordano

docs/src/FAQ.md

@@ -66,12 +66,14 @@ Since this package is unregistered, you have to use the full [`PackageSpec`](htt
     Dependency(PackageSpec(; name = "Libfoo_jll",  uuid = "...", url = "https://github.com/MY_USERNAME/Libfoo_jll.jl.git"))
 ```
 
-You can of course in turn build and deply this package with
+You can of course in turn build and deploy this package with
 
 ```
 julia build_tarballs.jl --debug --verbose --deploy="MY_USERNAME/Quxlib_jll.jl"
 ```
 
+Note that `PackageSpec` can also point to a local path: e.g., `PackageSpec(; name="Libfoo_jll", uuid="...", path="/home/myname/.julia/dev/Libfoo_jll")`.  This is particularly useful when [building a custom JLL package locally](@ref), instead of deploying it to a remote Git repository.
+
 ### What are those numbers in the list of sources?  How do I get them?
 
 The list of sources is a vector of [`BinaryBuilder.AbstractSource`](@ref)s.  What the hash is depends on what the source is:

docs/src/troubleshooting.md

@@ -6,6 +6,12 @@ This page collects some known build errors and trick how to fix them.
 
 ## All platforms
 
+### General comments
+
+While below you will find some tips about common problems found when building packages in BinaryBuilder, keep in mind that if something fails during the build, there is not a magic recipe to fix it: you will need to understand what the problem is.  Most of the time it's a matter of trial-and-error.  The best recommendation is to access the build environment and carefully read the log files generated by the build systems: it is not uncommon that build systems would only print to screen misleading error messages, and the actual problem is completely different (e.g. "library XYZ can't be found", when the problem instead is that the command they run to look for library XYZ fails for unrelated reasons, for example for a wrong compiler flag used in the check).  Having an understanding of what the build system is doing would also be extremely useful.
+
+You are welcome to open a pull request to [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil/) with a non-working build recipe, or ask for help in the `#binarybuilder` channel in the [JuliaLang Slack](https://julialang.org/slack/).  Someone will likely help you out if and when they are available, like for any support provided by volunteers.
+
 ### Header files of the dependencies can't be found
 
 Sometimes the build system can't find the header files of the dependencies, even if they're properly installed.  When this happens, you have to inform the C/C++ preprocessor where the files are.