Skip to content

Commit 045d7e8

Browse files
bobzhangbobzhang
committed
add docs about build system
1 parent 264757f commit 045d7e8

File tree

8 files changed

+222
-119
lines changed

8 files changed

+222
-119
lines changed

‎docs/Manual.html

+77-14
Original file line numberDiff line numberDiff line change
@@ -621,6 +621,7 @@ <h1><a href="https://github.com/bloomberg/bucklescript">BuckleScript</a> User Ma
621621
<li><a href="#_examples_3">Examples</a></li>
622622
</ul>
623623
</li>
624+
<li><a href="#_build_system_support">Build system support</a></li>
624625
<li><a href="#_faq">FAQ</a></li>
625626
<li><a href="#_high_level_compiler_workflow">High Level compiler workflow</a>
626627
<ul class="sectlevel2">
@@ -648,8 +649,9 @@ <h1><a href="https://github.com/bloomberg/bucklescript">BuckleScript</a> User Ma
648649
<li><a href="#_difference_from_a_href_https_github_com_ocsigen_js_of_ocaml_js_of_ocaml_a">Difference from <a href="https://github.com/ocsigen/js_of_ocaml">js_of_ocaml</a></a></li>
649650
</ul>
650651
</li>
651-
<li><a href="#_changes">Appendix A: CHANGES</a></li>
652-
<li><a href="#_1_1_0_dev">1.1.0(dev)</a></li>
652+
<li><a href="#_1_1_1_dev">Appendix A: 1.1.1(dev)</a></li>
653+
<li><a href="#_changes">CHANGES</a></li>
654+
<li><a href="#_1_1_0">1.1.0</a></li>
653655
<li><a href="#_1_03">1.03</a></li>
654656
<li><a href="#_1_02">1.02</a></li>
655657
<li><a href="#_1_01">1.01</a></li>
@@ -3664,15 +3666,13 @@ <h3 id="_examples_3"><a class="anchor" href="#_examples_3"></a>Examples</h3>
36643666
</div>
36653667
</div>
36663668
<div class="sect1">
3667-
<h2 id="_faq"><a class="anchor" href="#_faq"></a>FAQ</h2>
3669+
<h2 id="_build_system_support"><a class="anchor" href="#_build_system_support"></a>Build system support</h2>
36683670
<div class="sectionbody">
3669-
<div class="qlist qanda">
3670-
<ol>
3671-
<li>
3672-
<p><em>How to adapt your build system?</em></p>
3673-
<p>The BuckleScript compilation model is the same as the OCaml compiler.
3671+
<div class="paragraph">
3672+
<p>The BuckleScript compilation model is similar to OCaml native compiler.
36743673
If <code>b.ml</code> depends on <code>a.ml</code>, you have to compile <code>a.ml</code> <strong>and</strong> <code>a.mli</code>
36753674
first.</p>
3675+
</div>
36763676
<div class="admonitionblock note">
36773677
<table>
36783678
<tr>
@@ -3690,26 +3690,29 @@ <h2 id="_faq"><a class="anchor" href="#_faq"></a>FAQ</h2>
36903690
</table>
36913691
</div>
36923692
<div class="paragraph">
3693+
<p>BuckleScript distribution has <code>bsdep.exe</code> which has the same interface as <code>ocamldep</code></p>
3694+
</div>
3695+
<div class="paragraph">
36933696
<p>Here is a simple Makefile to get started:</p>
36943697
</div>
36953698
<div class="listingblock">
36963699
<div class="title">Makefile</div>
36973700
<div class="content">
36983701
<pre class="pygments highlight"><code data-lang="make"><span class="tok-nv">OCAMLC</span><span class="tok-o">=</span>bsc.exe <b class="conum">(1)</b>
3699-
<span class="tok-nv">OCAMLDEP</span><span class="tok-o">=</span>ocamldep <b class="conum">(2)</b>
3702+
<span class="tok-nv">OCAMLDEP</span><span class="tok-o">=</span>bsdep.exe <b class="conum">(2)</b>
37003703
<span class="tok-nv">SOURCE_LIST</span> <span class="tok-o">:=</span> src_a src_b
37013704
<span class="tok-nv">SOURCE_MLI</span> <span class="tok-o">=</span> <span class="tok-k">$(</span>addsuffix .mli, <span class="tok-k">$(</span>SOURCE_LIST<span class="tok-k">))</span>
37023705
<span class="tok-nv">SOURCE_ML</span> <span class="tok-o">=</span> <span class="tok-k">$(</span>addsuffix .ml, <span class="tok-k">$(</span>SOURCE_LIST<span class="tok-k">))</span>
37033706
<span class="tok-nv">TARGETS</span> <span class="tok-o">:=</span> <span class="tok-k">$(</span>addsuffix .cmj, <span class="tok-k">$(</span>SOURCE_LIST<span class="tok-k">))</span>
37043707
<span class="tok-nv">INCLUDES</span><span class="tok-o">=</span>
37053708
<span class="tok-nf">all</span><span class="tok-o">:</span> <span class="tok-k">$(</span><span class="tok-nv">TARGETS</span><span class="tok-k">)</span>
3706-
<span class="tok-nf">%.cmi</span><span class="tok-o">:</span> %.<span class="tok-n">mli</span>
3709+
<span class="tok-nf">.mli</span><span class="tok-o">:</span>.<span class="tok-n">cmi</span>
37073710
<span class="tok-k">$(</span>OCAMLC<span class="tok-k">)</span> <span class="tok-k">$(</span>INCLUDES<span class="tok-k">)</span> <span class="tok-k">$(</span>COMPFLAGS<span class="tok-k">)</span> -c <span class="tok-nv">$&lt;</span>
3708-
<span class="tok-nf">%.ml</span><span class="tok-o">:</span> %.<span class="tok-n">cmj</span>:
3711+
<span class="tok-nf">.ml</span><span class="tok-o">:</span>.<span class="tok-n">cmj</span>:
37093712
<span class="tok-k">$(</span>OCAMLC<span class="tok-k">)</span> <span class="tok-k">$(</span>INCLUDES<span class="tok-k">)</span> <span class="tok-k">$(</span>COMPFLAGS<span class="tok-k">)</span> -c <span class="tok-nv">$&lt;</span>
37103713
<span class="tok-cp">-include .depend</span>
37113714
<span class="tok-nf">depend</span><span class="tok-o">:</span>
3712-
<span class="tok-k">$(</span>OCAMLDEP<span class="tok-k">)</span> <span class="tok-k">$(</span>INCLUDES<span class="tok-k">)</span> <span class="tok-k">$(</span>SOURCE_ML<span class="tok-k">)</span> <span class="tok-k">$(</span>SOURCE_MLI<span class="tok-k">)</span> <span class="tok-p">|</span> sed -e <span class="tok-s1">&#39;s/\.cmx/.cmj/g&#39;</span> &gt; .depend</code></pre>
3715+
<span class="tok-k">$(</span>OCAMLDEP<span class="tok-k">)</span> <span class="tok-k">$(</span>INCLUDES<span class="tok-k">)</span> <span class="tok-k">$(</span>SOURCE_ML<span class="tok-k">)</span> <span class="tok-k">$(</span>SOURCE_MLI<span class="tok-k">)</span> &gt; .depend</code></pre>
37133716
</div>
37143717
</div>
37153718
<div class="colist arabic">
@@ -3722,8 +3725,62 @@ <h2 id="_faq"><a class="anchor" href="#_faq"></a>FAQ</h2>
37223725
</li>
37233726
</ol>
37243727
</div>
3728+
<div class="paragraph">
3729+
<p>In theory, people need run <code>make depend &amp;&amp; make all</code>, <code>make depend</code> will calculate dependency
3730+
while <code>make all</code> will do the job.</p>
3731+
</div>
3732+
<div class="paragraph">
3733+
<p>However, in practice, people used to use a file watch service,
3734+
take <a href="https://facebook.github.io/watchman/">watchman</a> for example, you need json configure</p>
3735+
</div>
3736+
<div class="listingblock">
3737+
<div class="title">build.json</div>
3738+
<div class="content">
3739+
<pre class="pygments highlight"><code data-lang="json"><span class="tok-p">[</span>
3740+
<span class="tok-s2">&quot;trigger&quot;</span><span class="tok-p">,</span> <span class="tok-s2">&quot;.&quot;</span><span class="tok-p">,</span> <span class="tok-p">{</span>
3741+
<span class="tok-nt">&quot;name&quot;</span><span class="tok-p">:</span> <span class="tok-s2">&quot;build&quot;</span><span class="tok-p">,</span>
3742+
<span class="tok-nt">&quot;expression&quot;</span><span class="tok-p">:</span> <span class="tok-p">[</span><span class="tok-s2">&quot;pcre&quot;</span><span class="tok-p">,</span> <span class="tok-s2">&quot;(\\.(ml|mll|mly|mli|sh|sh)$|Makefile)&quot;</span><span class="tok-p">],</span> <b class="conum">(1)</b>
3743+
<span class="tok-nt">&quot;command&quot;</span><span class="tok-p">:</span> <span class="tok-p">[</span><span class="tok-s2">&quot;./build.sh&quot;</span><span class="tok-p">],</span>
3744+
<span class="tok-nt">&quot;append_files&quot;</span> <span class="tok-p">:</span> <span class="tok-kc">true</span>
3745+
<span class="tok-p">}</span>
3746+
<span class="tok-p">]</span></code></pre>
3747+
</div>
3748+
</div>
3749+
<div class="colist arabic">
3750+
<ol>
3751+
<li>
3752+
<p>whenever such files changed, it will trigger <code>command</code> field to be run</p>
3753+
</li>
3754+
</ol>
3755+
</div>
3756+
<div class="listingblock">
3757+
<div class="title">build.sh</div>
3758+
<div class="content">
3759+
<pre class="pygments highlight"><code data-lang="sh">make -r -j8 all <b class="conum">(1)</b>
3760+
make depend <b class="conum">(2)</b></code></pre>
3761+
</div>
3762+
</div>
3763+
<div class="colist arabic">
3764+
<ol>
3765+
<li>
3766+
<p>build</p>
37253767
</li>
37263768
<li>
3769+
<p>update the dependency</p>
3770+
</li>
3771+
</ol>
3772+
</div>
3773+
<div class="paragraph">
3774+
<p>Now in your working directory, type <code>watchman -j &lt; build.json</code> and enjoy the lightning build speed.</p>
3775+
</div>
3776+
</div>
3777+
</div>
3778+
<div class="sect1">
3779+
<h2 id="_faq"><a class="anchor" href="#_faq"></a>FAQ</h2>
3780+
<div class="sectionbody">
3781+
<div class="qlist qanda">
3782+
<ol>
3783+
<li>
37273784
<p><em>How does IO work in browser?</em></p>
37283785
<p>In general, it is very hard to simulate IO in browser, we recommend users to write bindings to NodeJS directly for server side, or use <code>Js.log</code> in client side, see disucssions in <a href="https://github.com/bloomberg/bucklescript/issues/748">#748</a></p>
37293786
</li>
@@ -4444,13 +4501,19 @@ <h3 id="_difference_from_a_href_https_github_com_ocsigen_js_of_ocaml_js_of_ocaml
44444501
</div>
44454502
</div>
44464503
<div class="sect1">
4447-
<h2 id="_changes"><a class="anchor" href="#_changes"></a>Appendix A: CHANGES</h2>
4504+
<h2 id="_1_1_1_dev"><a class="anchor" href="#_1_1_1_dev"></a>Appendix A: 1.1.1(dev)</h2>
4505+
<div class="sectionbody">
4506+
4507+
</div>
4508+
</div>
4509+
<div class="sect1">
4510+
<h2 id="_changes"><a class="anchor" href="#_changes"></a>CHANGES</h2>
44484511
<div class="sectionbody">
44494512

44504513
</div>
44514514
</div>
44524515
<div class="sect1">
4453-
<h2 id="_1_1_0_dev"><a class="anchor" href="#_1_1_0_dev"></a>1.1.0(dev)</h2>
4516+
<h2 id="_1_1_0"><a class="anchor" href="#_1_1_0"></a>1.1.0</h2>
44544517
<div class="sectionbody">
44554518
<div class="ulist">
44564519
<ul>

0 commit comments

Comments
 (0)