PageRenderTime 47ms CodeModel.GetById 19ms RepoModel.GetById 0ms app.codeStats 0ms

/Bespin/BespinEmbedded/docs/devguide/index.html

https://bitbucket.org/raffel/node-host
HTML | 183 lines | 129 code | 37 blank | 17 comment | 0 complexity | 45e2a570da759b6e27153a6b62074a34 MD5 | raw file
    

  1. <!DOCTYPE html>
    2. 

  2. <html lang="en">
    3. 

  3. <head>
    4. 

  4. 	<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8">
    5. 

  5. 

  6. 	<title>Bespin Developer's Guide</title>
    7. 

    8. 

  8. 	<link rel="stylesheet" type="text/css" href="../css/reset.css">
    9. 

  9. 	<link rel="stylesheet" type="text/css" href="../css/stylesheet.css" media="screen,projection">
    10. 

  10. 	<link rel="stylesheet" type="text/css" href="../css/colorful.css">
    11. 

  11. </head>
    12. 

  12. <body>
    13. 

  13. 

  14. <!-- MAIN CONTAINER -->
    15. 

  15. <div id="main-container">
    16. 

  16. 

  17. <!-- MENU -->
    18. 

  18. <ul id="menu">
    19. 

  19. 	<li><a href="../index.html" title="Home">Home</a></li>
    20. 

  20. 	<li><a href="../userguide/index.html" title="User Guide">Using Bespin</a></li>
    21. 

  21. 	<li><a href="../pluginguide/index.html" title="Plugin Guide">Creating Plugins</a></li>
    22. 

  22. 	<li><a href="../embedding/index.html" title="Embedding Bespin in your app">Embedding</a></li>
    23. 

  23. 	<li class="current"><a href="../devguide/index.html" title="Developer's Guide">Developing Bespin</a></li>
    24. 

  24. </ul>
    25. 

  25. <!-- / MENU -->
    26. 

  26. 

  27. <h1 id="web-title">Bespin Developer's Guide</h1>
    28. 

  28. <h2 id="web-subtitle">Getting Started</h2>
    29. 

  29. 

  30. <!-- INDEX PAGE -->
    31. 

  31. 

  32. <!-- MAIN COLUMN -->
    33. 

  33. <div id="maincol">
    34. 

  34. <h2>Installing the Bespin Server</h2>
    35. 

  35. <p>Important note: The Bespin Server is going to undergo a complete rework.
    36. 

  36. You can read more about this in the <a href="http://groups.google.com/group/bespin/browse_thread/thread/6de8c718d64232a0">Bespin Server Roadmap</a>
    37. 

  37. that was posted to the mailing list.</p>
    38. 

  38. <p>To work on Bespin, you'll need to install the Bespin server on your local computer.</p>
    39. 

  39. <p>You can easily get Bespin's Python server running on your local Mac or Linux machine (see note about Windows below).</p>
    40. 

  40. <h2>Prerequisites</h2>
    41. 

  41. <p>You will need the following installed on your system to get Bespin up and running: </p>
    42. 

  42. <ul>
    43. 

  43. <li>Mercurial </li>
    44. 

  44. <li>Python 2.5 or 2.6 </li>
    45. 

  45. </ul>
    46. 

  46. <p>Python 2.6 is preferred.</p>
    47. 

  47. <p><strong>NOTE FOR LINUX USERS:</strong> <em>If you are running on a Linux system, you will likely need a "python-dev" and "ruby1.8-dev" (on Ubuntu; possibly "python-devel" elsewhere) package installed, if you do not already have it. If you want to build the embedded release, you will want libyaml: the package on Ubuntu is "libyaml-dev".</em> </p>
    48. 

  48. <p><strong>NOTE FOR MAC USERS:</strong> <em>You will need Xcode installed.</em> </p>
    49. 

  49. <p><strong>NOTE FOR WINDOWS USERS:</strong> <em>Most Bespin developers are using unix-like platforms. Bespin's server should be able to run on Windows, though. You'll need a C compiler, and you can use Microsoft's free [http://www.microsoft.com/Express/VC/ Visual C++] compiler. As an alternative, you can use [http://www.cygwin.com/ Cygwin] or [http://www.mingw.org/ MinGW] to have a unix-like environment on your Windows system.</em></p>
    50. 

  50. <h2>Getting Started</h2>
    51. 

  51. <p>Run:</p>
    52. 

  52. <div class="codehilite"><pre><span class="n">hg</span> <span class="n">clone</span> <span class="n">http:</span><span class="sr">//</span><span class="n">hg</span><span class="o">.</span><span class="n">mozilla</span><span class="o">.</span><span class="n">org</span><span class="sr">/labs/</span><span class="n">bespinclient</span><span class="o">/</span>
    53. 

  53. <span class="n">hg</span> <span class="n">clone</span> <span class="n">http:</span><span class="sr">//</span><span class="n">hg</span><span class="o">.</span><span class="n">mozilla</span><span class="o">.</span><span class="n">org</span><span class="sr">/labs/</span><span class="n">bespinserver</span><span class="o">/</span>
    54. 

  54. <span class="n">cd</span> <span class="n">bespinclient</span>
    55. 

  55. </pre></div>
    56. 

  56. 

  57. 

  58. <p>This will get the Bespin client and Python Bespin server code checked out. The <code>bespinclient/</code> directory is the "main" directory that you'll use.</p>
    59. 

  59. <p>To set up Bespin for the first time, run:</p>
    60. 

  60. <div class="codehilite"><pre><span class="n">python</span> <span class="n">bootstrap</span><span class="o">.</span><span class="n">py</span> <span class="o">--</span><span class="nb">no</span><span class="o">-</span><span class="n">site</span><span class="o">-</span><span class="n">packages</span>
    61. 

  61. </pre></div>
    62. 

  62. 

  63. 

  64. <p>to get the environment set up. This is built around <a href="virtualenv">http://pypi.python.org/pypi/virtualenv</a>. Please watch for helpful hints and instructions on screen.</p>
    65. 

  65. <p>In Unix-like environments, the next step is to activate the virtualenv using this command:</p>
    66. 

  66. <div class="codehilite"><pre><span class="n">source</span> <span class="n">bin</span><span class="o">/</span><span class="n">activate</span>
    67. 

  67. </pre></div>
    68. 

  68. 

  69. 

  70. <p>on Windows, the command is Scripts/activate.bat</p>
    71. 

  71. <p>Once the virtualenv is activate, you need to get the server set up:</p>
    72. 

  72. <div class="codehilite"><pre><span class="n">paver</span> <span class="n">install_server</span>
    73. 

  73. </pre></div>
    74. 

  74. 

  75. 

  76. <p>And the first time around, you're also going to want to get a database set up:</p>
    77. 

  77. <div class="codehilite"><pre><span class="n">paver</span> <span class="n">create_db</span>
    78. 

  78. </pre></div>
    79. 

  79. 

  80. 

  81. <p>If you have some trouble on macos x like the error message: ImportError: No module named `xxx'
    82. 

  82. It's probably cause the server side is not completely installed so try:</p>
    83. 

  83. <div class="codehilite"><pre><span class="n">cd</span> <span class="o">../</span><span class="n">bespinserver</span>
    84. 

  84. <span class="n">paver</span> <span class="n">develop</span>
    85. 

  85. <span class="n">paver</span> <span class="n">create_db</span>
    86. 

  86. </pre></div>
    87. 

    88. 

    89. 

  89. <h2>Starting the development server</h2>
    90. 

  90. <p>If you are no longer (or not yet) in the virtualenv environment run within the bespinclient directory:</p>
    91. 

  91. <p>source bin/activate</p>
    92. 

  92. <p>To start the server execute:</p>
    93. 

  93. <p>paver start</p>
    94. 

  94. <p>This will start the Bespin server. You can now access the Bespin editor at http://localhost:8080/ in you browser.</p>
    95. 

  95. <p>Have fun!</p>
    96. 

  96. <h2>Coding Conventions</h2>
    97. 

  97. <p>JavaScript code should follow the <a href="http://javascript.crockford.com/code.html">Crockford Code Conventions</a>. With a few minor modifications:</p>
    98. 

  98. <ul>
    99. 

  99. <li>
    100. 

  100. <p>Namespaces: Crockford does not mention namespaces, probably because owning the global namespace allows you to use as much as you want. Our code is likely to be used in many different places so we should not pollute the global namespace needlessly. Our code is organized in [http://commonjs.org/specs/modules/1.0.html CommonJS] modules, so every variable should either be a "var" or attached to the "exports" object.</p>
    101. 

  101. </li>
    102. 

  102. <li>
    103. 

  103. <p>_private: We agree that prefixing variables with an underscore provides no actual protection, however we think of it as a warning. "Use of this member is unsupported and likely to break without warning in future revisions". In early versions of Bespin where we are experimenting a lot, allowing 3rd parties to join in the experiment is valuable. As Bespin becomes more stable and finalized, we might expect underscored members to be replaced with closure scoped variables.</p>
    104. 

  104. </li>
    105. 

  105. <li>
    106. 

  106. <p>Documentation: Bespin JavaScript is documented with <a href="http://code.google.com/p/jsdoc-toolkit/w/list">JSDoc</a>, which in practice means prefixing functions with a set of comments that use various tags.</p>
    107. 

  107. </li>
    108. 

  108. <li>
    109. 

  109. <p>var first: The standard recommends putting var statements as the first statements in the function body. Crockford doesn't always follow this advice and we reserve the right to follow this lead ;-)</p>
    110. 

  110. </li>
    111. 

  111. </ul>
    112. 

  112. </div>
    113. 

  113. <!-- / MAIN COLUMN -->
    114. 

    115. 

  115. <!-- SIDEBAR -->
    116. 

  116. <div id="sidebar">
    117. 

    118. 

    119. 

    120. 

    121. 

    122. 

    123. 

    124. 

    125. 

  125. <h2 class="compact">Contents</h2>
    126. 

  126. <ul class="compact">
    127. 

  127. <li><a href="index.html">Getting Started</a></li>
    128. 

  128. <li><a href="tour.html">A Tour of the Code</a></li>
    129. 

  129. <li><a href="testplan.html">Manual Test Plan</a></li>
    130. 

  130. </ul>
    131. 

    132. 

    133. 

    134. 

  134. </div>
    135. 

  135. <!-- / SIDEBAR -->
    136. 

    137. 

  137. <!-- / MAIN CONTAINER -->
    138. 

  138. </div>
    139. 

    140. 

  140. <!-- FOOTER -->
    141. 

  141. <div id="footer">
    142. 

  142. 	<!-- COLUMN ONE -->
    143. 

  143. 	<div>
    144. 

  144. 	<h2 class="compact">Useful Links</h2>
    145. 

  145. 	<ul class="compact">
    146. 

  146. 		<li><a href="http://mozillalabs.com/bespin/">Bespin project home page</a></li>
    147. 

  147. 		<li><a href="https://wiki.mozilla.org/Labs/Bespin">Wiki</a></li>
    148. 

  148. 	</ul>
    149. 

  149. 	</div>
    150. 

  150. 	<!-- / COLUMN ONE -->
    151. 

    152. 

  152. 	<!-- COLUMN TWO -->
    153. 

  153. 	<div>
    154. 

  154. 	<h2 class="compact">Developer Resources</h2>
    155. 

  155. 	<ul class="compact">
    156. 

  156. 	  <li><a href="http://hg.mozilla.org/labs/bespinclient/">Main Code Repository</a></li>
    157. 

  157. 	  <li><a href="http://hg.mozilla.org/labs/bespinserver/">Python server repository</a></li>
    158. 

  158. 		<li><a href="http://groups.google.com/group/bespin-core/">bespin-core mailing list for developers</a></li>
    159. 

  159. 		<li><a href="http://groups.google.com/group/bespin-commits/">bespin-commits mailing list for repository commit messages</a></li>
    160. 

  160. 		<li><a href="https://bugzilla.mozilla.org/buglist.cgi?product=bespin">Bug List</a></li>
    161. 

  161. 	</ul>
    162. 

  162. 	</div>
    163. 

  163. 	<!-- / COLUMN TWO -->
    164. 

    165. 

  165. 	<!-- COLUMN THREE -->
    166. 

  166. 	<div>
    167. 

  167. 	<h2 class="compact">Get Help</h2>
    168. 

  168. 	<ul class="compact">
    169. 

  169. 		<li>The <a href="http://groups.google.com/group/bespin/">Bespin mailing list</a></li>
    170. 

  170. 		<li>Via IRC: <a href="irc://irc.mozilla.org/bespin">#bespin on irc.mozilla.org</a></li>
    171. 

  171. 	</ul>
    172. 

    173. 

  173. 	<h2 class="compact">Documentation Template</h2>
    174. 

  174. 	<ul class="compact">
    175. 

  175. 		<li>Adapted from a design by <a href="http://www.mgrabovsky.is-game.com/">Matěj Grabovský</a></li>
    176. 

  176. 	</ul>
    177. 

  177. 	</div>
    178. 

  178. 	<!-- / COLUMN THREE -->
    179. 

  179. </div>
    180. 

  180. <!-- / FOOTER -->
    181. 

    182. 

  182. </body>
    183. 

  183. </html>
    184.