Skip to content

Commit 79e3551

Browse files
bobzhangbobzhang
committed
more docs about bsb
1 parent d3519f4 commit 79e3551

File tree

3 files changed

+344
-14
lines changed

3 files changed

+344
-14
lines changed

‎docs/Manual.html

Lines changed: 199 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -639,6 +639,7 @@ <h1><a href="https://github.com/bloomberg/bucklescript">BuckleScript</a> User Ma
639639
<li><a href="#_mark_your_directory_as_dev_only">Mark your directory as dev only</a></li>
640640
</ul>
641641
</li>
642+
<li><a href="#_a_real_world_example_of_using_code_bsb_code">A real world example of using <code>bsb</code></a></li>
642643
<li><a href="#_build_using_make">Build using Make</a></li>
643644
</ul>
644645
</li>
@@ -3340,6 +3341,15 @@ <h2 id="_js_module"><a class="anchor" href="#_js_module"></a>Js module</h2>
33403341
<div class="sect1">
33413342
<h2 id="_extended_compiler_options"><a class="anchor" href="#_extended_compiler_options"></a>Extended compiler options</h2>
33423343
<div class="sectionbody">
3344+
<div class="exampleblock">
3345+
<div class="content">
3346+
<div class="paragraph">
3347+
<p>This section is only for people who want roll their own build system instead of using the recommended build system: <a href="#_bucklescript_build_system_code_bsb_code">BuckleScript build system: <code>bsb</code></a>,
3348+
in general, it is safe to skip this section.
3349+
It also adds some tips for people who debug the compiler.</p>
3350+
</div>
3351+
</div>
3352+
</div>
33433353
<div class="paragraph">
33443354
<p>BuckleScript inherits the command line arguments of the
33453355
<a href="http://caml.inria.fr/pub/docs/manual-ocaml/comp.html">OCaml compiler</a>. It
@@ -3870,7 +3880,28 @@ <h3 id="_bucklescript_build_system_code_bsb_code"><a class="anchor" href="#_buck
38703880
</div>
38713881
<div class="paragraph">
38723882
<p><code>bsb</code> can be running in any subdirectory, it is a schema based build tool, the schema is
3873-
<a href="http://bloomberg.github.io/bucklescript/docson/#build-schema.json">available</a></p>
3883+
<a href="http://bloomberg.github.io/bucklescript/docson/#build-schema.json">available</a>, it is strongly recommended to <strong>check out the <a href="http://bloomberg.github.io/bucklescript/docson/#build-schema.json">schema</a></strong>
3884+
after you finish reading the tutorials below.</p>
3885+
</div>
3886+
<div class="paragraph">
3887+
<p>If your editors support JSON schema validation and auto-completion like <a href="https://code.visualstudio.com/docs/languages/json">VSCode</a>,
3888+
below is a configuration to help you get auto-completion and validation for free:</p>
3889+
</div>
3890+
<div class="listingblock">
3891+
<div class="title">settings.json</div>
3892+
<div class="content">
3893+
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
3894+
<span class="tok-s2">&quot;json.schemas&quot;</span><span class="tok-o">:</span> <span class="tok-p">[</span>
3895+
<span class="tok-p">{</span>
3896+
<span class="tok-s2">&quot;fileMatch&quot;</span><span class="tok-o">:</span> <span class="tok-p">[</span>
3897+
<span class="tok-s2">&quot;bsconfig.json&quot;</span>
3898+
<span class="tok-p">],</span>
3899+
<span class="tok-s2">&quot;url&quot;</span> <span class="tok-o">:</span> <span class="tok-s2">&quot;file:///path/to/bucklescript/docs/docson/build-schema.json&quot;</span> <b class="conum">(1)</b>
3900+
<span class="tok-p">}</span>
3901+
<span class="tok-p">],</span>
3902+
<span class="tok-c1">// ....</span>
3903+
<span class="tok-p">}</span></code></pre>
3904+
</div>
38743905
</div>
38753906
<div class="paragraph">
38763907
<p>The build system is installed as <code>bsb.exe</code> in <code>bs-platform/bin/bsb.exe</code>, due to a known issue in npm,
@@ -3885,8 +3916,7 @@ <h3 id="_bucklescript_build_system_code_bsb_code"><a class="anchor" href="#_buck
38853916
<div class="content">
38863917
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
38873918
<span class="tok-s2">&quot;name&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;test&quot;</span><span class="tok-p">,</span> <span class="tok-c1">// package name, required </span><b class="conum">(1)</b>
3888-
<span class="tok-s2">&quot;sources&quot;</span><span class="tok-o">:</span>
3889-
<span class="tok-p">{</span> <span class="tok-s2">&quot;dir&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;src&quot;</span><span class="tok-p">}</span> <b class="conum">(2)</b>
3919+
<span class="tok-s2">&quot;sources&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;src&quot;</span> <b class="conum">(2)</b>
38903920
<span class="tok-p">}</span></code></pre>
38913921
</div>
38923922
</div>
@@ -3901,7 +3931,7 @@ <h3 id="_bucklescript_build_system_code_bsb_code"><a class="anchor" href="#_buck
39013931
</ol>
39023932
</div>
39033933
<div class="paragraph">
3904-
<p>The entry point is <code>bsb.exe</code>,
3934+
<p>The entry point is <code>bsb</code>,
39053935
it will check if there is already <code>build.ninja</code> in the build directory,
39063936
if not or need regenerated it will generate a file <code>build.ninja</code>
39073937
and delegate the hard work to <code>ninja</code>.</p>
@@ -3947,9 +3977,20 @@ <h3 id="_bucklescript_build_system_code_bsb_code"><a class="anchor" href="#_buck
39473977
<div class="listingblock">
39483978
<div class="title">Watch mode</div>
39493979
<div class="content">
3950-
<pre class="pygments highlight"><code data-lang="sh">bsb -w</code></pre>
3980+
<pre class="pygments highlight"><code data-lang="sh">bsb <b class="conum">(1)</b>
3981+
bsb -w <b class="conum">(2)</b></code></pre>
39513982
</div>
39523983
</div>
3984+
<div class="colist arabic">
3985+
<ol>
3986+
<li>
3987+
<p>Do the plain build</p>
3988+
</li>
3989+
<li>
3990+
<p>Do the plain build and watch</p>
3991+
</li>
3992+
</ol>
3993+
</div>
39533994
<div class="sect3">
39543995
<h4 id="_build_with_other_bucklescript_dependencies"><a class="anchor" href="#_build_with_other_bucklescript_dependencies"></a>Build with other BuckleScript dependencies</h4>
39553996
<div class="paragraph">
@@ -3998,7 +4039,8 @@ <h4 id="_build_with_other_bucklescript_dependencies"><a class="anchor" href="#_b
39984039
<div class="listingblock">
39994040
<div class="content">
40004041
<pre class="pygments highlight"><code data-lang="sh">bsb -clean-world <b class="conum">(1)</b>
4001-
bsb -make-world <b class="conum">(2)</b></code></pre>
4042+
bsb -make-world <b class="conum">(2)</b>
4043+
bsb -w <b class="conum">(3)</b></code></pre>
40024044
</div>
40034045
</div>
40044046
<div class="colist arabic">
@@ -4009,8 +4051,19 @@ <h4 id="_build_with_other_bucklescript_dependencies"><a class="anchor" href="#_b
40094051
<li>
40104052
<p>Build dependencies and lib itself</p>
40114053
</li>
4054+
<li>
4055+
<p>Start watching the project, whenever your changes are made, <code>bsb</code> will rebuild incrementally</p>
4056+
</li>
40124057
</ol>
40134058
</div>
4059+
<div class="paragraph">
4060+
<p>You can also stream-line the three commands as below:</p>
4061+
</div>
4062+
<div class="listingblock">
4063+
<div class="content">
4064+
<pre class="pygments highlight"><code data-lang="sh">bsb -clean-world -make-world -w</code></pre>
4065+
</div>
4066+
</div>
40144067
</div>
40154068
<div class="sect3">
40164069
<h4 id="_mark_your_directory_as_dev_only"><a class="anchor" href="#_mark_your_directory_as_dev_only"></a>Mark your directory as dev only</h4>
@@ -4039,6 +4092,145 @@ <h4 id="_mark_your_directory_as_dev_only"><a class="anchor" href="#_mark_your_di
40394092
</div>
40404093
</div>
40414094
<div class="sect2">
4095+
<h3 id="_a_real_world_example_of_using_code_bsb_code"><a class="anchor" href="#_a_real_world_example_of_using_code_bsb_code"></a>A real world example of using <code>bsb</code></h3>
4096+
<div class="paragraph">
4097+
<p>Below is a json configuration for the <a href="https://github.com/OvermindDL1/bucklescript-tea">bucklescript-tea</a>: the Elm artchitecture in BuckleScript</p>
4098+
</div>
4099+
<div class="listingblock">
4100+
<div class="title">bsconfig.json</div>
4101+
<div class="content">
4102+
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
4103+
<span class="tok-s2">&quot;name&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;bucklescript-tea&quot;</span><span class="tok-p">,</span>
4104+
<span class="tok-s2">&quot;version&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;0.1.3&quot;</span><span class="tok-p">,</span>
4105+
<span class="tok-s2">&quot;sources&quot;</span><span class="tok-o">:</span> <span class="tok-p">[</span>
4106+
<span class="tok-s2">&quot;src&quot;</span><span class="tok-p">,</span> <b class="conum">(1)</b>
4107+
<span class="tok-p">{</span>
4108+
<span class="tok-s2">&quot;dir&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;test&quot;</span><span class="tok-p">,</span>
4109+
<span class="tok-s2">&quot;type&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;dev&quot;</span> <b class="conum">(2)</b>
4110+
<span class="tok-p">}</span>
4111+
<span class="tok-p">]</span>
4112+
<span class="tok-p">}</span></code></pre>
4113+
</div>
4114+
</div>
4115+
<div class="colist arabic">
4116+
<ol>
4117+
<li>
4118+
<p>Source directory, by default it will export all units of this directory to users</p>
4119+
</li>
4120+
<li>
4121+
<p>Dev directory, which will only be useful for developers of this project</p>
4122+
</li>
4123+
</ol>
4124+
</div>
4125+
<div class="listingblock">
4126+
<div class="title">package.json</div>
4127+
<div class="content">
4128+
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
4129+
<span class="tok-s2">&quot;name&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;bucklescript-tea&quot;</span><span class="tok-p">,</span>
4130+
<span class="tok-s2">&quot;version&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;0.1.3&quot;</span><span class="tok-p">,</span>
4131+
<span class="tok-s2">&quot;description&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;TEA for Bucklescript&quot;</span><span class="tok-p">,</span>
4132+
<span class="tok-s2">&quot;scripts&quot;</span><span class="tok-o">:</span> <span class="tok-p">{</span>
4133+
<span class="tok-s2">&quot;build&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;bsb&quot;</span><span class="tok-p">,</span>
4134+
<span class="tok-s2">&quot;watch&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;bsb -w&quot;</span><span class="tok-p">,</span>
4135+
<span class="tok-s2">&quot;test&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;echo \&quot;Error: no test specified\&quot; &amp;&amp; exit 1&quot;</span>
4136+
<span class="tok-p">},</span>
4137+
<span class="tok-s2">&quot;peerDependencies&quot;</span><span class="tok-o">:</span> <span class="tok-p">{</span>
4138+
<span class="tok-s2">&quot;bs-platform&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;^1.4.2&quot;</span> <b class="conum">(1)</b>
4139+
<span class="tok-p">}</span>
4140+
<span class="tok-p">}</span></code></pre>
4141+
</div>
4142+
</div>
4143+
<div class="colist arabic">
4144+
<ol>
4145+
<li>
4146+
<p>Here we list <code>bs-platform</code> as a peer dependency so that different repos shares the same compiler</p>
4147+
</li>
4148+
</ol>
4149+
</div>
4150+
<div class="paragraph">
4151+
<p>Now, we have a repo <a href="https://github.com/bobzhang/bucklescript-have-tea">bucklescript-have-tea</a> to depend on <code>bucklescript-tea</code>, its configurations are as below:</p>
4152+
</div>
4153+
<div class="listingblock">
4154+
<div class="title">bsconfig.json</div>
4155+
<div class="content">
4156+
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
4157+
<span class="tok-s2">&quot;name&quot;</span> <span class="tok-o">:</span> <span class="tok-s2">&quot;bucklescript-have-tea&quot;</span><span class="tok-p">,</span>
4158+
<span class="tok-s2">&quot;sources&quot;</span> <span class="tok-o">:</span> <span class="tok-s2">&quot;src&quot;</span><span class="tok-p">,</span>
4159+
<span class="tok-s2">&quot;bs-dependencies&quot;</span><span class="tok-o">:</span> <span class="tok-p">[</span>
4160+
<span class="tok-s2">&quot;bucklescript-tea&quot;</span>
4161+
<span class="tok-p">]</span>
4162+
<span class="tok-p">}</span></code></pre>
4163+
</div>
4164+
</div>
4165+
<div class="listingblock">
4166+
<div class="title">package.json</div>
4167+
<div class="content">
4168+
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
4169+
<span class="tok-s2">&quot;name&quot;</span> <span class="tok-o">:</span> <span class="tok-s2">&quot;bucklescript-have-tea&quot;</span><span class="tok-p">,</span>
4170+
<span class="tok-s2">&quot;version&quot;</span> <span class="tok-o">:</span> <span class="tok-s2">&quot;0.1.0&quot;</span><span class="tok-p">,</span>
4171+
<span class="tok-s2">&quot;dependencies&quot;</span> <span class="tok-o">:</span> <span class="tok-p">{</span> <span class="tok-s2">&quot;bucklescript-tea&quot;</span> <span class="tok-o">:</span> <span class="tok-s2">&quot;^0.1.2&quot;</span> <span class="tok-p">},</span> <b class="conum">(1)</b>
4172+
<span class="tok-s2">&quot;peerDependencies&quot;</span> <span class="tok-o">:</span> <span class="tok-p">{</span> <span class="tok-s2">&quot;bs-platform&quot;</span> <span class="tok-o">:</span> <span class="tok-s2">&quot;^1.4.2&quot;</span> <span class="tok-p">}</span> <b class="conum">(2)</b>
4173+
<span class="tok-p">}</span></code></pre>
4174+
</div>
4175+
</div>
4176+
<div class="colist arabic">
4177+
<ol>
4178+
<li>
4179+
<p>List <code>bucklescript-tea</code> as dependency</p>
4180+
</li>
4181+
<li>
4182+
<p>List <code>bs-platform</code> as peer dependency</p>
4183+
</li>
4184+
</ol>
4185+
</div>
4186+
<div class="paragraph">
4187+
<p>Suppose you are in <code>bucklescript-have-tea</code> top directory,</p>
4188+
</div>
4189+
<div class="listingblock">
4190+
<div class="content">
4191+
<pre class="pygments highlight"><code data-lang="sh">npm install <b class="conum">(1)</b>
4192+
npm install bs-platform <b class="conum">(2)</b>
4193+
./node_modules/.bin/bsb -clean-world -make-world -w <b class="conum">(3)</b></code></pre>
4194+
</div>
4195+
</div>
4196+
<div class="colist arabic">
4197+
<ol>
4198+
<li>
4199+
<p>Install the dependencies</p>
4200+
</li>
4201+
<li>
4202+
<p>Install peer dependencies</p>
4203+
</li>
4204+
<li>
4205+
<p>Run the build</p>
4206+
</li>
4207+
</ol>
4208+
</div>
4209+
<div class="paragraph">
4210+
<p>You can also change the <code>package-specs</code> to have another module format, for example, tweak your <code>bsconfig.json</code>:</p>
4211+
</div>
4212+
<div class="listingblock">
4213+
<div class="content">
4214+
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
4215+
<span class="tok-p">...</span> <span class="tok-p">,</span>
4216+
<span class="tok-s2">&quot;package-specs&quot;</span> <span class="tok-o">:</span> <span class="tok-p">[</span><span class="tok-s2">&quot;amdjs&quot;</span><span class="tok-p">,</span> <span class="tok-s2">&quot;commonjs&quot;</span><span class="tok-p">],</span>
4217+
<span class="tok-p">...</span>
4218+
<span class="tok-p">}</span></code></pre>
4219+
</div>
4220+
</div>
4221+
<div class="paragraph">
4222+
<p>Rerun the command</p>
4223+
</div>
4224+
<div class="listingblock">
4225+
<div class="content">
4226+
<pre class="pygments highlight"><code data-lang="sh">bsb -clean-world -make-world</code></pre>
4227+
</div>
4228+
</div>
4229+
<div class="paragraph">
4230+
<p>You will get both <code>commonjs</code> and <code>amdjs</code> support, in the end, we suggest you <a href="http://bloomberg.github.io/bucklescript/docson/#build-schema.json">check out the schema</a> and enjoy the build!</p>
4231+
</div>
4232+
</div>
4233+
<div class="sect2">
40424234
<h3 id="_build_using_make"><a class="anchor" href="#_build_using_make"></a>Build using Make</h3>
40434235
<div class="admonitionblock warning">
40444236
<table>
@@ -4049,7 +4241,7 @@ <h3 id="_build_using_make"><a class="anchor" href="#_build_using_make"></a>Build
40494241
<td class="content">
40504242
<div class="paragraph">
40514243
<p><code>bsb</code> is officialy recommended build system, this section is listed here only for people who
4052-
are curious about how the build works</p>
4244+
are <em>curious</em> about how the build works</p>
40534245
</div>
40544246
</td>
40554247
</tr>

0 commit comments

Comments
 (0)