diff --git a/doc/tech.md b/doc/tech.md index d19ffc8..07a04ea 100644 --- a/doc/tech.md +++ b/doc/tech.md @@ -1,11 +1,9 @@ -## Technicalities - ### Technology plan for implementation The intial modest outline for bootstrapping dyna3 is as follows: -- dyna3 will be an npm project, but as it runs entirely client-side, there's no initial concern for being able to run under Node.js. However, npm will be useful as a dependency manager and build tool -- The package will build into a top-level site/directory, which will contain all and only the files that must be on a server to deliver dyna3 to a client browser. Everything in site/ will generated from the package files; nothing in site/ will be committed to the repository. Right now the planned contents a of site/ are just a handful of top-level files, the modules/ directory for in-package javascript, the /doc directory for generated documentation, and a copy of the node_modules/ directory as a backup for the external dependencies. +- dyna3 will be an npm project, but as it runs entirely client-side, there's no initial concern for being able to run under Node.js. However, npm will be useful as a dependency manager and build tool. In addition, helper scripts for the build can be run via node. +- The package will build into a top-level site/ directory, which will contain all and only the files that must be on a server to deliver dyna3 to a client browser. Everything in site/ will generated from the package files; nothing in site/ will be committed to the repository. Right now the planned contents a of site/ are just a handful of top-level files, the modules/ directory for in-package javascript, the /doc directory for generated documentation, and a copy of the node_modules/ directory as a backup for the external dependencies. - Literate coffeescript modules (in the src/modules directory except for the top-level application) will compile into individual js modules in the site/modules directory (again, except for the top-level application) - Why coffeescript? The motivation for the javascript family of languages is wide deployability and availability of numerous libraries; the motivation for coffeescript is that it (still) reduces the amount of punctuation and extraneous characters from Javascript, resulting in better readability. And Literate coffeescript so that the manual and code are co-located. - The list of external modules will be harvested from npm, automatically generating a site/modules/externals.js from which specific external items can be imported into the local modules. Within externals.js, modules will be imported from the appropriate CDN, with a fallback to a copy in site/node_modules/ for when the CDN is off line. diff --git a/src/dyna3.litcoffee b/src/dyna3.litcoffee index 8a82d3e..ffd2fa8 100644 --- a/src/dyna3.litcoffee +++ b/src/dyna3.litcoffee @@ -6,22 +6,22 @@ When you load dyna3, you should initially see a three-dimensional coordinate sys import {threeLoaded, three as J3} from './externals.js' main = () -> - renderer = new J3.WebGLRenderer() - rwd = window.innerWidth - rht = window.innerHeight - renderer.setSize(rwd, rht) - document.body.appendChild renderer.domElement + renderer = new J3.WebGLRenderer() + rwd = window.innerWidth + rht = window.innerHeight + renderer.setSize(rwd, rht) + document.body.appendChild renderer.domElement - scene = new J3.Scene() - geometry = new J3.SphereBufferGeometry(1, 5, 5) - material = new J3.MeshBasicMaterial( {color: 0x0000ff} ) - ball = new J3.Mesh(geometry, material) - scene.add ball + scene = new J3.Scene() + geometry = new J3.SphereBufferGeometry(1, 5, 5) + material = new J3.MeshBasicMaterial( {color: 0x0000ff} ) + ball = new J3.Mesh(geometry, material) + scene.add ball - camera = new J3.PerspectiveCamera(75, rwd/rht, 0.1, 1000) - camera.position.z = 5 + camera = new J3.PerspectiveCamera(75, rwd/rht, 0.1, 1000) + camera.position.z = 5 - renderer.render(scene, camera) + renderer.render(scene, camera) threeLoaded.then(main) ``` diff --git a/src/helpers/pkglock_to_externals.litcoffee b/src/helpers/pkglock_to_externals.litcoffee new file mode 100644 index 0000000..2919bee --- /dev/null +++ b/src/helpers/pkglock_to_externals.litcoffee @@ -0,0 +1,59 @@ +### External dependencies + +The dyna3 program depends on some externally-maintained JavaScript +libraries/modules. The package uses npm to track these external dependencies. +A module externals.js is automatically generated from the package_lock.json file +created by npm to load the necessary modules at runtime. + +The generation is performed by pkglock_to_externals.litcoffee, which also +records the main importable file within the library, as there does not seem +to be a systematic way to generate that filename from the module name. +```javascript + + importable = { three: 'build/three.module.js' } + +``` +Currently, dyna3 makes use of the following external libraries: +```javascript + + if process.argv.length < 3 + header = + """ + /* External module loader for dyna3 + * Generated automatically from package-lock.json by + * helpers/pkglock_to_externals.litcoffee + */ + + """ + process.stdout.write header + fs = require 'fs' + pl = fs.readFileSync 'package-lock.json' + pdata = JSON.parse pl + for dep in Object.keys pdata.dependencies + if process.argv.length > 2 + process.stdout.write "* #{dep}\n" + else + block = + """ + export var #{dep}; + export var #{dep}Loaded = new Promise(async function(resolve, reject) { + var success = false; + try { + #{dep} = await import('https://cdn.jsdelivr.net/npm/#{dep}@#{pdata.dependencies[dep].version}/#{importable[dep]}'); + console.log('CDN import of #{dep} module OK'); + success = true; + } catch(err) { + try { + #{dep} = await import('./node_modules/#{dep}/#{importable[dep]}'); + success = true; + } catch(err) { + } + console.log('Used local fallback for #{dep} module'); + } + if (success) { resolve(); } else { reject(); } + }); + + """ + process.stdout.write block + +```