-
Notifications
You must be signed in to change notification settings - Fork 1
/
get-involved.html
340 lines (319 loc) · 19.6 KB
/
get-involved.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title> get involved - creating luapower packages </title>
<script src="jquery.js"></script>
<script src="jquery-cookie.js"></script>
<script src="jquery-tablesorter.js"></script>
<script src="strftime.js"></script>
<script src="mustache.js"></script>
<script src="config.js"></script>
<script src="main.js"></script>
<link rel="stylesheet" type="text/css" href="templates/reset.css" />
<link rel="stylesheet" type="text/css" href="templates/hack.css" />
<link rel="stylesheet" type="text/css" id="lights_css" />
<script>
var DOCNAME = 'get-involved'
var PROJECT = ''
//set the lights before rendering starts
set_lights()
</script>
</head>
<body>
<header>
<div class="container">
<div class="btn-container btn-lights-container">
<a href="#" class="btn btn-lights" id="lights">lights</a>
</div>
<div class="btn-container btn-home-container">
<a href="/" class="btn btn-home">luapower</a>
</div>
<table id="header_table">
<tr>
<td style="vertical-align: middle;" width="100%">
<h1> get involved </h1>
<h2> creating luapower packages </h2>
</td>
<td style="vertical-align: middle;" align="right" style="height: 150px">
</td>
</tr>
</table>
</div>
</header>
<div class="bg-container">
<div class="bg-center-container">
<div class="bg bg-get-involved" style="background-image: url('bg/get-involved.png');"></div>
</div>
</div>
<div class="under-header">
<div class="container">
<div id="toc_container" class="toc_container doc"></div>
<button id=tab1_button class="tab_button hidden">Documentation</button>
<button id=tab2_button class="tab_button hidden">Package Info</button>
<div id="tabs_cointainer">
<div id="tab1_container">
<section class="doc">
<span id="module_info"></span>
<blockquote>
<p>NOTE: This page is all about rules, so necessarily you will have issues with it.</p>
</blockquote>
<h2 id="anatomy-of-a-package">Anatomy of a package</h2>
<p>There are 5 types of luapower packages:</p>
<ul>
<li><strong>Lua module</strong>: written in Lua, compatible with LuaJIT2, Lua 5.1 and optionally Lua 5.2</li>
<li><strong>Lua/C module</strong>: written in C using the Lua C API, compatible with LuaJIT2, Lua 5.1 and optionally Lua 5.2</li>
<li><strong>Lua+ffi module</strong>: written in Lua using the LuaJIT ffi extension, compatible with LuaJIT2 and optionally with Lua ffi; the C library it binds to is included in the package in source and binary form</li>
<li><strong>C module</strong>: binary dependency or support library for other module; source and binary included</li>
<li><strong>other</strong>: none of the above: media/support files, etc.</li>
</ul>
<h3 id="directory-layout">Directory layout</h3>
<ul>
<li>main module: <code>foo.lua</code></li>
<li>submodule: <code>foo_bar.lua</code> but <code>foo/bar.lua</code> is fine too</li>
<li>ffi cdef module: <code>foo_h.lua</code></li>
<li>test program: <code>foo_test.lua</code></li>
<li>demo: <code>foo_demo.lua</code></li>
<li>documentation: <code>foo.md</code>, <code>foo_bar.md</code> (pandoc markdown)</li>
<li>C libs & Lua/C libs:
<ul>
<li>sources: <code>csrc/foo/*</code></li>
<li>build scripts: <code>csrc/foo/build-<platform>.sh</code>
<ul>
<li>platforms are named mingw32, mingw64, linux32, linux64, osx32, osx64.</li>
</ul></li>
<li>binaries (resulted from building):
<ul>
<li>C libraries: <code>bin/mingw32/foo.dll</code>, <code>bin/linux32/libfoo.so</code></li>
<li>Lua/C libraries: <code>bin/<platform>/clib/foo[.dll|.so]</code></li>
</ul></li>
<li>description: <code>csrc/foo/WHAT</code> (see below)</li>
</ul></li>
<li>exclude file: <code>foo.exclude</code> (see below)</li>
<li>LuaJIT executable: <code>bin/<platform>/luajit[.exe]</code></li>
</ul>
<blockquote>
<p>These conventions allow packages to be safely unzipped over a common directory and the result look sane, and it makes it possible to extract package information and build the package database.</p>
</blockquote>
<h3 id="the-docs">The docs</h3>
<p>In order to appear on the website, docs should start with a yaml header:</p>
<pre><code>---
project: cairo
tagline: cairo graphics engine
---</code></pre>
<ul>
<li>the <code>project</code> field should match the git project's name - this makes the "view on github" and download buttons appear.</li>
<li><code>platforms: platform1, ...</code> should be added for Lua packages that are platform-specific but don't have a C component (eg. <a href="winapi.html">winapi</a>; for packages with a C component, adding the build scripts is enough to figure out the supported platforms).</li>
<li>a good, short tagline is important for figuring out what the module does when browsing the module list</li>
</ul>
<p>You don't have to make a doc for each submodule if you don't have much to document for it, a single doc matching the package name would suffice.</p>
<h3 id="the-what-file">The <code>WHAT</code> file</h3>
<p>The WHAT file is used for packages that have a C component (Lua+ffi, Lua/C or C packages), and it's used to describe that C component. Pure Lua packages don't need a WHAT file.</p>
<pre><code>cairo 1.12.16 from http://cairographics.org/releases/ (LGPL license)
requires: pixman, freetype, zlib, libpng</code></pre>
<ul>
<li>the first line should read <code><name> <version> from <browse-url> (<license>)</code></li>
<li>the second line should read <code>requires: package1, package2, ...</code> and it is only needed if the package has any binary dependencies.</li>
<li>after the first two lines and an empty line, you can type in additional notes, whatever, they aren't parsed.</li>
</ul>
<p>The WHAT file can also be used to describe Lua modules that are developed outside of luapower (eg. <a href="lexer.html">lexer</a>).</p>
<blockquote>
<p>Extracting dependencies from the dll itself and figuring it out from there is a project for another day.</p>
</blockquote>
<h3 id="the-exclude-file">The <code>exclude</code> file</h3>
<p>This is the .gitignore file used for excluding files between packages so that files in one packages don't show as untracked files in other package. Another way to think of it is the file used for reserving name-space in the luapower directory layout.</p>
<p>Example:</p>
<pre><code>* ; exclude all files
!/foo* ; include files in root that start with `foo`
!/foo/ ; include the directory in root named `foo`
!/foo/** ; include the contents of the directory named `foo`, recursively</code></pre>
<blockquote>
<p>NOTE: Double-asterisk patterns are Git 1.8.2+.</p>
</blockquote>
<h3 id="the-code">The code</h3>
<ul>
<li>adding at least a small comment on the first line of every Lua file with a short tagline (what the module does), author and license can be a huge barrier-remover towards approaching your code (adding a full screen of legal crap on the other hand is just bad taste - IMHO).</li>
<li>adding a comment on top of the <code>foo_h.lua</code> file describing the origin (which files? which version?) and process (cpp? by hand?) used for generating the file adds confidence that the C API is complete and updated.</li>
<li>calling <code>ffi.load()</code> without paths, custom names or version numbers keeps the module away from any decision regarding how and where the library is to be found, which in turn this allows for more freedom on how to deploy libraries.</li>
<li>the reason for putting cdefs in a separate file is because they may contain types that other packages might need. If this is an unlikely scenario and the API is small, you can embed the cdefs in the main module file directly.</li>
<li>(subjective) I don't use <code>module()</code> to keep _G clean. For big modules with a shared namespace I make a "namespace" module and use <code>setfenv(1, require'foo.ns')</code> as the first line of every submodule (see <a href="winapi.html">winapi</a>).</li>
<li>(subjective) my code is indented with tabs, and alignment inside the line is done with spaces, because I think that a fixed tabsize should not be enforced on people (plus very few editors can jump through space indentation).</li>
<li>(subjective) I use Lua's naming conventions <code>foo_bar</code> and <code>foobar</code> instead of FooBar or fooBar.</li>
</ul>
<h3 id="the-build-scripts">The build scripts</h3>
<p>Write a build script for each supported platform, based on the <a href="building.html">luapower toolchain</a> (do not introduce additional tool requirements if you can avoid it). Building with gcc is a 2-step process, compilation and linking, becuase we want to build both static and dynamic versions the libraries.</p>
<p>Here's a quick gcc cheat list:</p>
<h4 id="compiling-with-gccg">Compiling with gcc/g++:</h4>
<pre><code>gcc -c options... files...
g++ -c options... files...</code></pre>
<ul>
<li><code>-c</code> : compile only (don't link; produce .o files)</li>
<li><code>-O2</code> : enable code optimizations</li>
<li><code>-I<dir></code> : search path for headers (eg. <code>-I../lua</code>)</li>
<li><code>-D<name></code> : set a <code>#define</code></li>
<li><code>-D<name>=<value></code> : set a <code>#define</code></li>
<li><code>-U<name></code> : unset <code>#define</code></li>
<li><code>-fpic</code> or <code>-fPIC</code> : generate position-independent code (required for linux64)</li>
<li><code>-DWINVER=0x501</code> : set Windows API level to Windows XP</li>
<li><code>-DWINVER=0x502</code> : set Windows API level to Windows XP SP2</li>
<li><code>-arch i386</code> : OSX: create 32bit x86 binaries</li>
<li><code>-arch x86_64</code> : OSX: create 64bit x86 binaries</li>
</ul>
<h4 id="dynamic-linking-with-gcc">Dynamic linking with gcc:</h4>
<pre><code>gcc -shared options... files...</code></pre>
<ul>
<li><code>-shared</code> : create a shared library</li>
<li><code>-s</code> : strip debug symbols (not for OSX)</li>
<li><code>-o <output-file></code> : output file path (eg. <code>-o ../../bin/mingw32/z.dll</code>)</li>
<li><code>-L<dir></code> : search path for library dependencies (eg. <code>-L../../bin/mingw32</code>)</li>
<li><code>-l<libname></code> : library dependency (eg. <code>-lz</code> looks for<code>z.dll</code>, <code>libz.so</code> or <code>libz.dylib</code> depending on platform)</li>
<li><code>-static-libstdc++</code> : static linking of the C++ standard library (for g++; not for OSX)</li>
<li><code>-static-libgcc</code> : static linking of the GCC library (for gcc and g++; not for OSX)</li>
<li><code>-static</code> : static linking of the winpthread library (for g++ mingw64)</li>
<li><code>-pthread</code> : enable pthread support (not for Windows)</li>
<li><code>-arch i386</code> : OSX: create 32bit x86 binaries</li>
<li><code>-arch x86_64</code> : OSX: create 64bit x86 binaries</li>
<li><code>-undefined dynamic_lookup</code> : required for Lua/C modules on OSX (don't link them to luajit!)</li>
<li><code>-mmacosx-version-min=10.6</code> : for C++ modules on OSX: link to libstdc++.6 instead of the newer libc++.1</li>
<li><code>-install_name @loader_path/<libname>.dylib</code> : for OSX, for libs that are binary dependencies to other libs</li>
</ul>
<h4 id="static-linking-with-ar">Static linking with ar:</h4>
<pre><code>ar rcs ../../bin/<platform>/static/<libname>.a *.o</code></pre>
<blockquote>
<p><strong>IMPORTANT</strong>: place the <code>-L</code> and <code>-l</code> switches <strong><em>after</em></strong> the input files!</p>
</blockquote>
<h4 id="example-compile-and-link-lpeg-0.10-for-linux32">Example: compile and link lpeg 0.10 for linux32:</h4>
<pre><code>gcc -c -O2 lpeg.c -I. -I../lua
gcc -shared -s -static-libgcc -o ../../bin/linux32/clib/lpeg.so
ar rcs ../../bin/linux32/static/liblpeg.so</code></pre>
<p>In some cases it's going to be more complicated than that.</p>
<ul>
<li>sometimes you won't get away with compiling <code>*.c</code> -- some libraries rely on the makefile to choose the C files that need to be compiled for a specific platform or set of options (eg. <a href="socket.html">socket</a>)</li>
<li>some libraries actually do use one or two of the myriad of defines generated by the <code>./configure</code> script -- you might have to grep for those and add appropriate <code>-D</code> switches to the command line.</li>
<li>some libraries have parts written in assembler or other language. At that point, maybe a simple makefile is a better alternative.</li>
<li>if the package has a clean and simple makefile that doesn't add more dependencies to the toolchain, use that.</li>
</ul>
<h2 id="publishing">Publishing</h2>
<h3 id="publishing-on-luapower.com">1. Publishing on luapower.com</h3>
<p>The way you add modules to luapower.com is:</p>
<ul>
<li>first you make a git repo that resembles a luapower package</li>
<li>then you can either:
<ul>
<li>publish it on your server or github account (luapower users will clone from that url directly)
<ul>
<li>I will add your package to the package database</li>
<li>I will periodically pull and update luapower.com</li>
</ul></li>
<li>publish it <em>and manage it</em> yourself on luapower.com
<ul>
<li>I will add you as an admin to the luapower github account (it's an organization account)</li>
<li>you will update luapower.com yourself</li>
</ul></li>
</ul></li>
</ul>
<h4 id="what-to-add">What to add</h4>
<p>Before publishing a luapower module, please consider:</p>
<ul>
<li>what name you plan to use for your module</li>
<li>how your module relates to other modules</li>
</ul>
<p>Choosing a good name is important if you want people to find your module on luapower.com and understand (from the name alone) what it does. Likewise, it's a good idea to be sure that your module is doing something new or at least different (and hopefully better) than something already on luapower.com.</p>
<p>Ideally, your module has:</p>
<ul>
<li><strong>distinction</strong> - focused problem domain</li>
<li><strong>completeness</strong> - exhaustive of the problem domain</li>
<li><strong>API documentation</strong> - so it can be integrated into luapower.com</li>
<li><strong>test and/or demo</strong> - so it can be seen to work</li>
<li><strong>a non-viral license</strong> - so it doesn't impose restrictions on <em>other</em> modules</li>
</ul>
<p>Of course, few modules (in any language) qualify on all fronts, so luapower.com is inevitably an ecclectic mix. In any case, if your module collection is too specialized to be added to luapower.com or you simply don't want to mix it in, here's where you can have your cake and eat it too.</p>
<h3 id="forking-luapower.com">2. Forking luapower.com</h3>
<p>Luapower can be easily forked and used as a personal website for publishing luapower modules.</p>
<p>Luapower is composed of:</p>
<ul>
<li>a <a href="https://github.com/luapower/luapower.github.io">static website</a> generated with pandoc templating</li>
<li>a <a href="https://github.com/luapower/luapower-git/blob/master/luapower.lua">Lua script</a> for updating the package database, navigation tree, and dependency lists offline</li>
<li>a few <a href="https://github.com/luapower/luapower-git">simple shell scripts</a> for working with git in a shared-work-tree environment</li>
</ul>
<p>Which means that with a few forks and a few tweaks you can have your own luapower clone with your own modules on it. The only dependency is <a href="http://johnmacfarlane.net/pandoc/">pandoc</a> for generating the website.</p>
<h4 id="the-luapower-command">The <code>luapower</code> command</h4>
<p>This is a powerful command that extracts and aggregates data from the luapower environment and gives detailed information about packages, modules and documentation. It can give accurate information about dependencies between modules and packages because it actually loads the module and tracks <code>require</code> calls, and then it integrates that information with the information about packages.</p>
<p>It is also used for generating the package database on luapower.com, along with the the dependency lists you see on each module's page.</p>
<p>The <code>luapower</code> command is a Lua script that depends on <a href="luajit.html">luajit</a>, <a href="lfs.html">lfs</a>, <a href="glue.html">glue</a> and <a href="tuple.html">tuple</a> so let's clone these first:</p>
<pre><code>> clone luajit
> clone lfs
> clone glue
> clone tuple</code></pre>
<p>For updating the website, we also need to clone its files in the <code>_site</code> sub-directory:</p>
<pre><code>> git clone https://github.com/luapower/luapower.github.io _site</code></pre>
<p>The rest you can learn from the tool itself:</p>
<pre><code>> luapower
USAGE: luapower <command> ...
HELP
help this screen
PACKAGES
packages list installed packages
known list all known package
left list not yet installed packages
PACKAGE INFO
describe <package> describe a package
type [package] package type
ver [package] current git version
tags [package] git tags
tag [package] current git tag
files [package] tracked files
docs [package] docs
modules [package] modules
scripts [package] scripts
mtree [package] module tree
mtags [package [module]] module info
platforms [package] supported platforms
ctags [package] C package info
CHECKS
check [package] consistency checks
trackable trackable files
multitracked files tracked by multiple packages
untracked files not tracked by any package
DATABASE
update-db [package] update _site/packages.json
update-toc [package] update _site/toc.md
update [package] update both _site/packages.json and _site/toc.md
rebuild-db rebuild _site/packages.json
DEPENDENCIES
requires <module> direct module requires
rall <module> direct and indirect module requires
rtree <module> module require log tree
rext <module> direct-external module requires
pall <module> direct and indirect package dependencies
pext <module> direct-external package dependencies
ppall [package] direct and indirect package dependencies
ppext [package] direct-external package dependencies
cdeps [package] direct and indirect C dependencies
rrev <module> all modules that require a module
The `package` arg defaults to the env var PROJECT, as set by the `proj` command,
and if that is not set, it defaults to `--all`, meaning all packages.</code></pre>
<h4 id="the-luapower-website">The luapower website</h4>
<p>Look into <code>_site/config.js</code> for what needs to be adjusted.</p>
</section>
</div>
<div id="tab2_container" class="doc"></div>
</div>
</div>
<div class="container">
<footer>
<div id="disqus_thread"></div>
<div class="faint">[email protected] | <a href="http://unlicense.org/">public domain</a></div>
</footer>
</div>
</div>
<script type="text/x-mustache" id=info_tab_template>
<h3>Modules</h3>
<ul>
{{#module_array}}
<li>{{name}}</li>
{{/module_array}}
</ul>
</script>
</body>
</html>