Create an FAQ for Buck.

Summary: Initial questions for the FAQ: Why doesn't Buck support Windows? Why is Buck built with Ant instead of Buck? I thought we should openly address some of the "Cons" listed on: https://gerrit.googlesource.com/gerrit/+/57a4d597cd1111ebabf9bbf495ecd45324e7acdd
aulanov · May 2, 2013 · 077abe0 · 077abe0
1 parent 4adf595
commit 077abe0
Showing 3 changed files with 95 additions and 0 deletions.
diff --git a/docs/__common.soy b/docs/__common.soy
@@ -132,6 +132,7 @@ ga('send', 'pageview');
     <li><a href="{ROOT}concept/build_target_pattern.html">Build Target Pattern</a>
     <li><a href="{ROOT}concept/visibility.html">Visibility</a>
     <li><a href="{ROOT}concept/troubleshooting.html">Troubleshooting</a>
+    <li><a href="{ROOT}concept/faq.html">FAQ</a>
   </ul>
   <li><span class="{css toc_header}">Build Rules</span>
   <ul>

diff --git a/docs/buck.css b/docs/buck.css
@@ -137,3 +137,11 @@ ul ul {
   right: 0;
   border: 0;
 }
+
+.faq {
+  margin-bottom: 1em;
+}
+
+.faq_q {
+  font-weight: bold; 
+}
diff --git a/docs/concept/faq.soy b/docs/concept/faq.soy
@@ -0,0 +1,86 @@
+{namespace buck.faq}
+
+
+/**
+ * @param id attribute for this blob of HTML so users can link to an individual FAQ. We should make
+ *     an effort to keep these identifiers stable to avoid breaking links. Therefore, when choosing
+ *     an id, try to make it generic enough so that it is forward-compatible.
+ * @param question Question.
+ * @param shortAnswer Try to keep this to a one-liner.
+ * @param? longAnswer This portion of the answer can include more detail.
+ */
+{template .faq}
+<div class="{css faq}" id="{$id|id}">
+  <div class="{css faq_q}">Q: {$question}</div>
+  <div class="{css faq_a}">
+    A: {$shortAnswer|noAutoescape}
+    {if $longAnswer}
+    <p>{$longAnswer|noAutoescape}
+    {/if}
+  <p></div>
+</div>
+{/template}
+
+
+/***/
+{template .soyweb}
+  {call buck.page}
+    {param title: 'FAQ' /}
+    {param content}
+
+{call .faq}
+  {param id: 'windows-support' /}
+  {param question}
+  Why doesn't Buck support Windows?
+  {/param}
+  {param shortAnswer}
+  There are a number of engineering tasks that need to be addressed before Buck will run on Windows.
+  {/param}
+  {param longAnswer}
+  <ul>
+    <li>Buck uses symlinks under the hood in many places. We need to map that concept to the Windows
+        equivalent throughout the codebase.
+    <li>Buck hardcodes the use of OS X/Linux file and path separators all over the place. This may
+        be a poor software design choice, but it makes the code more readable in many circumstances,
+        particularly in unit tests.
+    <li>Documentation becomes more work to maintain. For example, a nifty trick from the OS X/Linux
+        command line, such as:
+        <pre>buck targets --type java_test | xargs buck test</pre>
+        does not work on Windows, so that must be documented separately.
+    <li>The <code>./bin/buck</code> script is written in Bash, so to support Windows, the equivalent
+        would have to be maintained as a Windows Batch Script. Keeping both scripts in sync would be
+        non-trivial. Alternatively, the run script could be written in a platform-independent
+        language, such as Ruby, but that would require users to install an additional tool.
+    <li>It increases the surface area of what needs to be tested.
+  </ul>
+  Despite all of the work it will require, we do hope to support Windows in the future.
+  {/param}
+{/call}
+
+{call .faq}
+  {param id: 'why-is-buck-built-with-ant' /}
+  {param question}
+  Why is Buck built with Ant instead of Buck?
+  {/param}
+  {param shortAnswer}
+  Self-hosting systems can be more difficult to maintain and debug.
+  {/param}
+  {param longAnswer}
+  If Buck built itself using Buck, then every time a change was made to Buck's source,
+  the commit would have to include a new Buck binary that included that change. It would be easy to
+  forget to include the binary, difficult to verify that it was the correct binary, and wasteful to
+  bloat the Git history of the repository with binaries that could be rebuilt from source.
+  Building Buck using Ant ensures we are always building from source, which is simpler to verify.
+  <p>
+  Also, because Ant is a more mature build system than Buck, it has support for features that we
+  have not had time to include in Buck yet, such as generating Javadoc, static analysis
+  via <a href="http://pmd.sourceforge.net/">PMD</a>, Python unit tests, etc. 
+  <p>
+  That said, as a sanity check, Buck is capable of building itself. Once you build Buck using Ant,
+  you can re-build Buck using Buck by running <code>./bin/buck build buck</code>.  
+  {/param}
+{/call}
+
+    {/param}
+  {/call}
+{/template}