readium / readium-js-viewer

👁 ReadiumJS viewer: default web app for Readium.js library
BSD 3-Clause "New" or "Revised" License
556 stars 185 forks source link

Build system needs to be documented #372

Open danielweck opened 9 years ago

danielweck commented 9 years ago

Neither the (old) Grunt nor the (new) NPM -based build systems were/are documented, which made/makes it difficult for newcomers to modify build tasks (requiring reverse-engineering the workflow, dicyphering scattered tasks into a coherent sequence of actions).

In the case of the NPM-based build system, some improvements have taken place (centralized, organised scripts). The package.json file defines the available NPM "scripts" (NodeJS build tasks) but the CSON syntax is used to ease editing (and the master CSON file is split into separate items): https://github.com/readium/readium-js-viewer/tree/develop/package In addition, the readium-build-tools folder contains reusable scripts (which are used by all Readium repositories / projects), with the unfortunate design consequence of locating this file at the deepest level in the submodule hierarchy (we will need to fix this, see https://github.com/readium/readium-js-viewer/issues/373 ): https://github.com/readium/readium-cfi-js/tree/develop/readium-build-tools

danielweck commented 9 years ago

npm run prepare needs to be documented, notably: https://github.com/readium/readium-cfi-js/tree/develop/readium-build-tools

gitHubForksUpdater.js: how we check for upstream changes in forked external libraries patchRequireJS.js: how/why we patch the RequireJS optimizer optimizePackageJsonScripts.js: how we concat + preprocess CSON build scripts versionsMaker.js: how Git versioning info is fetched at build time (via NodeJS + Git commands), or at runtime (by the "live" RequireJS no-optimize index.html, via browser XmlHttpRequests) pluginsConfigMaker.js: how we create plugins config as a pre-build step RequireJS_config.js: how we handle 3 different RequireJS modes "no-optimize" (live browser refresh, no compilation), "single-bundle" (Almond AMD loader), "multiple-bundles" (regular RequireJS loader).