nlesc-jcer / run-cpp-on-web Goto Github PK

Some code blocks are quite long. Some reviewers commented that

• they are intimitidated by long code block which are not in their preferred language
• medium blogs have reading minutes attached to them, which might make blog post a longer read then expected

Certain long code blocks of should be replaced with links.

The blog uses emcc to compile, but existing C++ code will have a existing build system based on configure/cmake and make. Hint that emconfigure and emmake can reuse existing build system to compile to WebAssembly.

Start with web assembly blog

To attract users to vega we should make the plot look like the readers expect. Include title, units etc.

Using a web worker and WebAssembly I would like to know how to report progress of the calculation back to the user. Also my computation should be stopped when the user submits again or presses a cancel button.

When I was trying the webassembly blog, the emscripten invocation puzzled me: the argument createModule sounds like it may be a reserved name that cannot and should not be changed. In reality, this is just the name that is attached to the particular functionality that is exposed, IIUC. This could be made clear by using (for example) createNewtonRaphsonModule throughout. (The same goes for the other blogs.)

The blog should have titles:

1. web assembly, small static web page without user interaction
2. unblock ui with web worker, how to deal with tasks that take longer to complete
3. interactive form with React, gathering user inputs through a form in a simple react app
4. plot with Vega, displaying results from the algorithm in a more complex web app
5. blog which combines web-worker, form with React and plot with vega into single example

Add your title suggestions below, refer to blog number. Use single comment for each commiter

Do we want to add gist on GitHub and add links to those in the blog post?

• point to the Newton-Raphson algorithm (assume content exists already)
• just web assembly
• (don't talk about long running calculations, web workers)

• Long running JS web application js-async.md
• point to problem of blocking (assume content exists already); mention solution async
• web worker

I was reviewing the PR that removes the namespaces. I had to install some extra packages to test the code. Do we want to provide the users a Docker image which will contain all the tools needed?

• Fancy JS web application js-react.md
• react, json-schema form, vega plot
• point to webworker/async approach (assume the content exists)

In the first blog we claim web assembly is not significantly slower than native C++, we should point to a study which substantiate this.

I found

• https://arxiv.org/abs/1901.09056 , wasm 1.5x slower native
• https://youtu.be/aC_QLLilwso , prime example

https://help.medium.com/hc/en-us/articles/215679797-Images prefers images with width of 1400px, but most of our images are smaller.

find . \( -name \*png -o -name \*jpg -o -name \*jpeg -o -name \*gif \) -exec identify {} \;
./js-plot/scatter.png PNG 853x643 853x643+0+0 8-bit sRGB 34344B 0.000u 0:00.000
./js-plot/composite.png PNG 854x647 854x647+0+0 8-bit sRGB 51542B 0.000u 0:00.000
./js-plot/root-plot.png PNG 853x671 853x671+0+0 8-bit sRGB 27847B 0.000u 0:00.000
./js-kitchen-sink/1024px-Pack_Gong_(3144438149).jpg JPEG 1024x683 1024x683+0+0 8-bit sRGB 171208B 0.000u 0:00.000
./run-your-c++-code-on-the-web/result.png PNG 640x212 640x212+0+0 8-bit sRGB 12278B 0.000u 0:00.000
./run-your-c++-code-on-the-web/equation.png PNG 857x880 857x880+0+0 8-bit sRGB 39988B 0.000u 0:00.000
./run-your-c++-code-on-the-web/hold-your-horses.jpeg JPEG 1920x1248 1920x1248+0+0 8-bit sRGB 532478B 0.000u 0:00.000
./run-your-c++-code-on-the-web/newton.jpg JPEG 1275x1777 1275x1777+0+0 8-bit sRGB 1.20111MiB 0.000u 0:00.000

Current code does not throw exceptions, but may be usefull to explain how to convert error number to message.
See https://emscripten.org/docs/optimizing/Optimizing-Code.html#optimizing-code-exception-catching

or should we choose monte carlo estimation of pi instead? I do think it would be best to stick with one algorithm throughout all blogs if we can.

A few more nits on the C++ code.

• I concur with Daan that algebra.cpp is better included through a header. Or, in this case, it may be better to just make the equation and derivative functions members of the Newton-Raphson class altogether and ditch algebra.cpp altogether, since the expressions are hardcoded anyway.
• If algebra.cpp is kept: I found the name confusing.. How about problem.cpp, since that is what it defines?
• The function equation is better renamed into function or expression, since it becomes an equation only after requiring it be equal to zero.

To spread word of the published blogs we need to make some posts to social media. Let's prepare some tweets.

At the moment the equation (and its derivative) is hardcoded to 2x^3 - 4x^2 + 6 as a user I would like to use a different equation or change the multipliers. So for example

float equation(float x) {
  return a * x * x * x - b * x * x + c;
}

Where 'a','b' and 'c' can be configured from a submit form.

This one is related to the deployment using the python web server. If you follow the instructions literally, typing python3 -m http.server 8000, the process runs in the foreground. Since I wanted to see console output, I instead started it from a different console --- but failed to change to directory that contains the required files.

Maybe it could be explicitly stated that the command creates a web server that uses the pwd as root; that is serves documents such as index.html and scatter.html in the directory from which the server was started? Or perhaps add a & to the suggested command, so the process will run in the background and the console is available for subsequent commands?

• web assembly
• web worker
• React
• Vega
• Combined

Something like

More emphasis on UI though.

• webassembly
• web-worker
• react
• vega
• kitchen-sink

Medium stories can have tags. We should use them for our benefit.

I would be nice to tease reader what the final web application will look like in the first blog post

Python is an additional dependency that might not be installed on the users system. Emscripten installation includes nodejs. So we could use

npx http-server

npx: installed 23 in 1.963s
Starting up http-server, serving ./
Available on:
  http://127.0.0.1:8080
  http://192.168.1.202:8080
Hit CTRL-C to stop the server

keep track of the (x, y, y') as public property iterations array of struct?

iterations[0].x
iterations[0].y
iterations[0].dy

Issue that triggered this #16

Ask 3 C++ developers which blog should come after first blog.

PR #47

Why did we pick React over pure Javascript without dependencies

After publishing each blog post on medium, we should update the links in the blog text.

moved this snippet from https://github.com/NLESC-JCER/run-cpp-on-web/blame/2abe8c363736c4aae4f8176def9668bd531230ef/js-plot/README.md#L164-L181 to an issue:

<!--
TODO do we want to explain how we can run snippet below?

To run test the WebAssembly module in a web browser we can use it's build-in console

1. startup a web server to host newtonraphson.js and newtonraphson.wasm with `python3 -m http.server 8000`
2. goto webserver adress [http://localhost:8000](http://localhost:8080) in browser
3. open the console in the web browsers DevTools (press F12 to open)

Import the WebAssembly JavaScript binding file with

```javascript
const response = await fetch('http://localhost:8000/newtonraphson.js');
const text = await response.text();
eval(text);
const {NewtonRaphson} = await createModule();

-->

We want to have a mathematical function that shows a nice dip to illustrate the goal of the Newton-Raphson method well. This function should be used in every blog. We prefer consistent use of the function, consistent scaling, consistent style (all if possible of course).

• 1 webapp
• 2 responsive ui/webworker
• 3 react/web forms
• 4 plotting/vega
• 5 integration?

I changed it from what Stefan had (which I believe was compliant with conventions). Maybe we should ask the C++ peeps.

Steps to publish

1. create drafts on medium.com by importing READM.md's from GitHub, this will skip code blocks
2. update titles & clear subtitles
3. Add back author list, import skips text above h1
4. move image captions from text to caption of image
5. For web app screenshots/animated gids make clickable with CTRL-k
6. uncheck canonical link in advanced settings
7. add back h2 headers and bullet lists, (only h3 are copied during import)
8. create gists for all code blocks
9. embed gists by pressing enter, plus icon and embed the gist url
10. setup feature image if blog has an image in first section
11. setup tags #83
12. use post id to create link (https://blog.esciencecenter.nl/<kebab-case-tltle>-<post id>), so other blogs can link to it
13. update intra blog links #80
14. share draft links to team
15. share draft links to blog team
16. press publish

Medium can only render PNG, JPEG and GIF. We should not have SVG images in the README.md files.

Also, I'd suggest we pick an initial value within the bounds of the image -4 < x < 4

Thank you for creating this series of blog posts, they have already been very helpful. I want to share some minor remarks that I encountered while working with the posts.

1. WebAssembly

C++ related

It is quite unconventional to include a .cpp file (and it can e.g. lead to "multiple definition" errors). This can be solved by creating a file algebra.h that declares the functions:

#ifndef ALGEBRA_H
#define ALGEBRA_H

float equation(float x);
float derivative(float x);

#endif

then include this file from algebra.cpp and newtonraphson.cpp.

3. React

Minor remarks

• Line 96: 'answer' -> 'container'
• Line 100: a word is missing (e.g. should look like)

4. Visualizations

C++ related

• Same remarks as for the first blog post.

"we reuse the data via layers" -> not sure that's correct in visualization

The equation and algorithm is explained in first blog, a picture like https://nlesc-jcer.github.io/cpp2wasm/images/equation.svg with a big arrow to -1,0 coordinate would help me here.

Adding a workflow image which show the steps would make it more clear. It would also help readers that are looking for TL;DR.

It can be extended version of
https://nlesc-jcer.github.io/cpp2wasm/images/cgi.svg.png

Verify that we source/author/license for each image we used.