Skip to content

Commit 5666113

Browse files
author
Sébastien Loisel
committed
fixing github problem
1 parent c582aac commit 5666113

File tree

2 files changed

+214
-0
lines changed

2 files changed

+214
-0
lines changed

‎README.markdown

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
Numeric Javascript by Sébastien Loisel
2+
======================================
3+
4+
Numeric Javascript is a javascript library for doing numerical
5+
analysis in the browser. Because Numeric Javascript uses only the
6+
javascript programming language, it works in many browsers and does
7+
not require powerful servers.
8+
9+
Numeric Javascript is for building "web 2.0" apps that can perform
10+
complex calculations in the browser and thus avoid the latency of
11+
asking a server to compute something. Indeed, you do not need a
12+
powerful server (or any server at all) since your web app will perform
13+
all its calculations in the client.
14+
15+
For further information, see http://www.numericjs.com/
16+
Discussion forum: http://groups.google.com/group/numericjs
17+
18+
License
19+
-------
20+
21+
Numeric Javascript is copyright by Sébastien Loisel and is distributed
22+
under the MIT license. Details are found in the license.txt file.
23+
24+
Dependencies
25+
------------
26+
27+
There are no dependencies for numeric.js.
28+
29+
Subdirectories
30+
--------------
31+
32+
Here are some of the subdirectories and their contents:
33+
34+
* / holds the html/php files for the workshop/web site, license.txt, README, etc...
35+
36+
* /src holds the source files. The .js files are concatenated together to produce lib/numeric.js
37+
38+
* /lib holds numeric.js and numeric-min.js
39+
40+
* /resources holds some small images, css files, etc...
41+
42+
* /tools is all the scripts and auxiliary javascript libraries that are required for building, testing
43+
as well as some supplemental javascript libraries used by the workshop. There's a tools/README.markdown.
44+
45+
* /tools/deploy are the scripts that are used to deploy to the numericjs.com web site.
46+

‎tools/README.markdown

+168
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
The /tools directory
2+
====================
3+
4+
This directory contains build/test scripts for numeric.js as well as
5+
js libraries needed by the Workshop. I'm trying to keep things
6+
documented -- I hope this file doesn't bitrot.
7+
8+
Hosting your own Javascript Workshop
9+
====================================
10+
11+
You can host your own server that runs Javascript Workshop. You will
12+
need to set up MySQL, Apache and PHP and run either Linux or MacOS.
13+
14+
Setting up a Javascript Workshop server
15+
---------------------------------------
16+
17+
To set up a server that runs the Javascript Workshop, proceed as
18+
follows:
19+
20+
1. Set up Apache, MySQL and PHP. I use MacOS but Linux works too. In
21+
the rest of this, I denote the webroot by $webroot. For example, your
22+
webroot might be $webroot=~/public_html
23+
24+
2. Set up a file $webroot/.htaccess that will redirect traffic
25+
appropriately. This is what I have:
26+
RewriteEngine On
27+
RewriteRule ^staging/(.*)$ staging/$1 [L]
28+
RewriteRule ^scripts/(.*)$ scripts/$1 [L]
29+
RewriteRule ^numeric/(.*)$ numeric/$1 [L]
30+
RewriteRule ^(.*)$ numeric/$1 [L]
31+
The last rule ensures that, "by default", Apache reads from the
32+
numeric subdirectory. Therefore, accessing any content will look
33+
at the numeric subdirectory. The exception is that anything that
34+
starts with staging/ or scripts/. In that case, it is looked
35+
up in the staging/ or scripts/ subdirectory. This ensures that
36+
you can deploy to staging/ and test before you really deploy
37+
to numeric/.
38+
39+
3. Get the git tree into $webroot/numeric
40+
41+
4. Decompress $webroot/numeric/tools/scripts.tar.gz and move it to
42+
$webroot/scripts
43+
44+
5. Run $webroot/numeric/tools/mkdb.php at the command-line.
45+
46+
Then, every time you make some changes to anything, run the mkdb.php
47+
command again.
48+
49+
Deploying to a live server
50+
--------------------------
51+
52+
There is a two-step procedure for deploying to a live server so that
53+
the server hopefully never breaks. See the numeric/tools/deploy
54+
discussion below.
55+
56+
Hacking numeric.js
57+
==================
58+
59+
You can easily make small local modifications to numeric.js. However,
60+
to make bigger changes, to use the regression testing suite, to run
61+
the Selenium tests, etc..., you will need a more complete development
62+
environment.
63+
64+
Build dependencies
65+
------------------
66+
67+
You will need standard Linux/MacOS tools such as python, php, bash,
68+
etc... You also need to set up your machine to run Apache, MySQL and
69+
PHP as above and make sure that it runs Javascript Workshop as
70+
above. Furthermore, you will need to install the Selenium python
71+
bindings. For me, it was sufficient to do sudo easy_install selenium
72+
There is also some java stuff in the numeric/tools subdirectory
73+
(e.g. jsdoc-toolkit). I also have an eclipse project that
74+
automatically rebuilds the library every time I modify it and also
75+
automatically runs the regression suite. (I actually use Aptana
76+
Studio.) You will also need d8 (the developer console that comes
77+
with Google v8).
78+
79+
Building
80+
--------
81+
82+
I usually edit the files in the numeric/src directory. To produce the
83+
library from those files, run the numeric/tools/build.sh script (or
84+
cat the files together yourself but don't forget the numeric_header.js
85+
and numeric_footer.js in the tools subdirectory). In addition to
86+
performing this concatenation, the build.sh also runs a regression
87+
testing suite and also builds the documentation usign jsdoc-toolkit.
88+
89+
Main scripts
90+
------------
91+
92+
The numeric/tools subdirectory contains the following custom tools:
93+
94+
* numeric/tools/build.sh:
95+
Concatenates files and produces /lib/numeric.js, runs the unit tests
96+
by running numeric/tools/unit3.js in d8, builds the documentation
97+
by calling numeric/tools/mkdoc.sh. I set it up so that it is
98+
automatically called by eclipse every time I modify a file.
99+
100+
Note that Eclipse has no qualms about calling build.sh while another
101+
instance is still running. As a result, build.sh makes a small attempt
102+
at killing a previous instance. If you trigger build.sh very rapidly
103+
(milliseconds) it is conceivable that this mechanism would fail to
104+
catch it and then you would get multiple build.sh running at the same
105+
time, which is not really a big deal.
106+
107+
Note: build.sh expects to be called with its current directory set
108+
to numeric/tools.
109+
110+
Deployment scripts
111+
------------------
112+
113+
To deploy to a live web site without downtime, I have a two-step
114+
procedure. In this approach, the tree will be deployed to
115+
$webroot/vXXX, where XXX is a time stamp. Then, the symlink
116+
$webroot/staging -> $webroot/vXXX is created. Several tests are performed.
117+
If all is well then the symlink $webroot/numeric -> $webroot/vXXX is
118+
created, which deploys to the main web page.
119+
120+
* numeric/tools/deploy/stage.sh
121+
This shell script makes a tarball of the current tree and uploads it
122+
to the web site (as specified in numeric/tools/deploy/config.sh).
123+
The new tarball is unpacked on the web server under $webroot/vXXX and
124+
then creates the symlink $webroot/staging -> $webroot/vXXX.
125+
Subsequently, the test suites are run and the results are stored in
126+
$webroot/report.html
127+
128+
* numeric/tools/deploy/deploy.sh
129+
After running stage.sh, you normally check report.html and perhaps
130+
manually check the staging/ folder on the web site. If all is good,
131+
the deploy.sh will move this staging deployment to the main web site.
132+
Assuming that we have the symlinks $webroot/numeric -> $webroot/vYYY
133+
and $webroot/staging -> $webroot/vXXX, first the link $webroot/numeric
134+
is deleted. Then, the symlink $webroot/numeric -> $webroot/vXXX is
135+
created. Finally, the symlink $webroot/staging is deleted. Any directory
136+
$webroot/v* which is no longer linked is deleted with rm -rf.
137+
138+
After juggling the symlinks, a quick Selenium test is performed to
139+
ensure that the web site works properly.
140+
141+
Auxiliary scripts
142+
-----------------
143+
144+
* numeric/tools/unit2.js:
145+
It gets all the @example comments from /lib/numeric.js (also stuff in
146+
<pre>). Each line that begins with "> " is a test and the next line(s)
147+
is the expected output. Then unit2.js executes each line and checks
148+
the output, neglecting whitespace.
149+
150+
* numeric/tools/mkdoc.sh:
151+
Calls jsdoc-toolkit.
152+
153+
* numeric/tools/mkdb.php:
154+
Stores numeric/lib/numeric.js into the database so that it can be used
155+
in workshop. Then, it produces numeric/index.php from
156+
numeric/tools/index_in.php by making sure that the correct version of
157+
numeric.js is used. The file workshop.html also gets included.
158+
159+
* numeric/tools/selenium_tests.py:
160+
Runs all the unit tests in one or more browsers using Selenium.
161+
162+
* numeric/tools/selenium_links.py:
163+
Checks that the links in index.php go somewhere reasonable.
164+
165+
* numeric/tools/make_demo.py:
166+
Uses Selenium to load the index.php and put in the demo. Then,
167+
it saves this demo using the permalink button. Finally, it downloads
168+
the demo into demo.php.

0 commit comments

Comments
 (0)