Commit 8aa01392 authored by Gerrit Hübbers's avatar Gerrit Hübbers 🃏
Browse files

Expand build documentation.

parent 3dce877e
......@@ -19,7 +19,7 @@ var parseVersionFromPomXml = function() {
return version;
};
// usemin custom step
// [usemin user-defined step](https://github.com/yeoman/grunt-usemin#user-defined-steps-and-post-processors)
var useminAutoprefixer = {
name: 'autoprefixer',
createConfig: function(context, block) {
......@@ -56,7 +56,7 @@ module.exports = function (grunt) {
}
},
autoprefixer: {
// src and dest is configured in a subtask called "generated" by usemin
// src and dest is configured in a target called "generated", which is generated by useminPrepare via the user-defined step "useminAutoprefixer"
},
wiredep: {
app: {
......@@ -149,10 +149,10 @@ module.exports = function (grunt) {
}
},
concat: {
// src and dest is configured in a subtask called "generated" by usemin
// src and dest is configured in a target called "generated", which is automatically generated by useminPrepare, see https://github.com/yeoman/grunt-usemin#tasks
},
uglifyjs: {
// src and dest is configured in a subtask called "generated" by usemin
uglifyjs: { // TODO should this be "uglify" instead?
// src and dest is configured in a target called "generated", which is automatically generated by useminPrepare, see https://github.com/yeoman/grunt-usemin#tasks
},
rev: {
dist: {
......@@ -175,6 +175,8 @@ module.exports = function (grunt) {
steps: {
js: ['concat', 'uglifyjs'],
css: ['cssmin', useminAutoprefixer] // Let cssmin concat files so it corrects relative paths to fonts and images
//"useminAutoPrefixer" is a ["user-defined step"](https://github.com/yeoman/grunt-usemin#user-defined-steps-and-post-processors)
// "useminAutoPrefixer", as a CSS user-defined step, will make useminPrepare have a dynamically generated target `autoprefixer:generated`.
},
post: {}
}
......@@ -216,7 +218,7 @@ module.exports = function (grunt) {
}
},
cssmin: {
// src and dest is configured in a subtask called "generated" by usemin
// src and dest is configured in a target called "generated", which is automatically generated by useminPrepare, see https://github.com/yeoman/grunt-usemin#tasks
},
ngtemplates: {
dist: {
......
......@@ -139,6 +139,64 @@ The `dev` profile activates Java debugging capability. You can connect a client
|- scss/ <--- Gruntfile.js configures the grunt-sass task to process SASS stylesheets in this directory
|- webapp/ <--- in the final build artifact, its content will land in /. This content will be served out as files via HTTP!
### Build process
DDA is built with Maven. `pom.xml` configures the default `mvn` behavior to run the `spring-boot:run` goal and use the `dev` Maven profile.
#### Building with the default Maven `dev` profile
For the default maven `dev` profile, during the `generate-resources` phase, the `yeoman-maven-plugin` runs the following commands in *this* project's root directory: `npm install && bower install --no-color && grunt sass:server --force`. Let's take a look at each of these frontend-specific build steps:
##### `npm install`
`npm install` investigates file `/package.json` and downloads all (transitive) `dependencies` and `devDependencies` to directory `/node_modules`
##### `bower install --no-color`
`bower install --no-color` investigates file `/bower.json` and sees `appPath` configured to be `src/main/webapp`. Therefore, bower downloads all (transitive) `dependencies` and `devDependencies` to directory `/src/main/webapp/bower_components`
##### `grunt sass:server --force`
`grunt sass:server --force`: grunt interprets file `Gruntfile.js`. It uses [`load-grunt-tasks`](https://github.com/sindresorhus/load-grunt-tasks) to automatically find and register all grunt tasks in /node_modules/* by looking for the default `grunt-*` pattern, including the `sass` task. `Gruntfile.js` configures the `sass` task to have a [target](http://gruntjs.com/api/grunt.task#grunt.task.registermultitask) `sass:server`, which configures `grunt-sass` to find *DDA*'s source Sass stylesheets at `/src/main/scss/`, to find referenced `@imports` in `/src/main/webapp/bower_components/` (using underlying [`node-sass` option `includePaths`](https://github.com/sass/node-sass#options), and to put the generated `.css` output files to `/src/main/webapp/assets/styles/`.
Having this configured, grunt executes this Sass generation.
#### Building with the Maven `staging` profile
For the staging environment DDA is built with the Maven `staging` profile. Let's have a look what is happening when running `mvn clean package -Pstaging`.
The`yeoman-maven-plugin` runs the following commands in *this* project's root directory: `npm install && bower install --no-color && grunt test --no-color && grunt build --no-color`.
##### `grunt test --no-color`
`Gruntfile.js` registers a task `test`. It depends on the following subtasks:
* `clean:server`: this `grunt-contrib-clean` task will delete the [`.tmp` directory](http://stackoverflow.com/q/25621410/923560)
* `wiredep:test`: the `grunt-wiredep` task will update file `src/test/javascript/karma.conf.js` to include all Bower components for Karma tests.
* `ngconstant:dev`: this `grunt-ng-constant` task will create a file `/src/main/webapp/scripts/app/app.constants.js` which acts as an Angular module providing two constants: `ENV=dev` and `VERSION=${POM_VERSION}`.
* `sass:server`. See the discussion earlier in *this* documentation. This task will take all SASS stylesheets from `/src/main/scss/` (and their transitive @import Bower dependencies), convert them to CSS, and place these CSS files into `src/main/webapp/assets/styles/`.
* `karma`: this `grunt-karma` task will use the previously updated configuration file `src/test/javascript/karma.conf.js` to configure Karma JavaScript tests:
* it loads the following [Karma plugins](https://karma-runner.github.io/1.0/config/plugins.html): `karma-script-launcher, karma-chrome-launcher, karma-html2js-preprocessor, karma-jasmine, karma-requirejs, karma-phantomjs-launcher, karma-coverage, karma-jenkins-reporter`.
* it activates [Coverage](https://karma-runner.github.io/0.8/config/coverage.html).
* it uses [Jasmine](https://jasmine.github.io/) as the testing framework
* it configures as reporters: [`dots`, `progress`](http://stackoverflow.com/a/25601443/923560), [`jenkins` for XML JUnit format reports](https://www.npmjs.com/package/karma-jenkins-reporter), and `Publish JUnit test result report`.
* it provides to the testing browser all of the following [`files`](http://karma-runner.github.io/1.0/config/files.html): all bower components, all AngularJS frontend files, and almost all files in `/src/test/javascript/**`
`karma-jasmine` will start up the AngularJS application, will additionally set up all Jasmine helpers (located in `/src/test/javascript/spec/helpers/**`) and then run all Jasmine `describe(..)` tests. These tests are located in `/src/test/javascript/spec/**`.
##### `grunt build --no-color`
`Gruntfile.js` registers a task `build`. It depends on the following subtasks:
* `clean:dist`: the `grunt-contrib-clean` task will delete the [`.tmp/`](http://stackoverflow.com/q/25621410/923560) and `/src/main/webapp/dist/` directories.
* `wiredep:app`: this `grunt-wiredep` task will update `/src/main/webapp/index.html` to include Bower JavaScript and Bower CSS dependencies. And will update `/src/main/scss/main.scss` to include Bower SCSS dependencies.
* `ngconstant:prod`: this `grunt-ng-constant` task will create a file `.tmp/scripts/app/app.constants.js` which acts as an Angular module providing two constants: `ENV=prod` and `VERSION=${POM_VERSION}`.
* `useminPrepare`: this [`grunt-usemin`](https://github.com/yeoman/grunt-usemin#the-useminprepare-task) task takes file `/src/main/webapp/index.html` and examines all its `build:js` and `build:css` blocks. It will then dynamically add to the Grunt configuration additional tasks targets, `concat:generated`, `uglifyjs:generated`, `cssmin:generated` and `autoprefixer:generated`.
* `ngtemplates`: this [`grunt-angular-templates`](https://github.com/ericclemmons/grunt-angular-templates) task takes all jHipster- and DDA-specific HTML files and generates a n HTML-minified, JavaScript-based templates file from it to location `/.tmp/templates/templates.js`.
* `sass:server`: See the discussion earlier in *this* documentation. This task will take all SASS stylesheets from `/src/main/scss/` (and their transitive `@import` Bower dependencies), convert them to CSS, and place these CSS files into `src/main/webapp/assets/styles/`.
* `imagemin`: this [`grunt-contrib-imagemin`](https://github.com/gruntjs/grunt-contrib-imagemin) task will take all JPEG images from directory `/src/main/webapp/assets/images/**`, minify them, and copy the results to `/src/main/webapp/dist/assets/images/`
* `svgmin`: this [`grunt-svgmin`](https://github.com/sindresorhus/grunt-svgmin) behaves identical to aforementioned `imagemin` task, but for SVG images.
* `concat`: this [`grunt-contrib-concat`](https://github.com/gruntjs/grunt-contrib-concat) task will execute the previously generated `concat:generated` target (generated by `useminPrepare`). This target bundles all DDA-specific JavaScript files into a single temporary file `/.tmp/concat/scripts/app.js` ... and all Bower JavaScript dependencies in a single temporary file `/.tmp/concat/scripts/vendor.js`.
* `copy:fonts`: this [`grunt-contrib-copy`](https://github.com/gruntjs/grunt-contrib-copy) target copies all Bootstrap fonts to `/src/main/webapp/dist/assets/fonts/`
* `copy:dist`: this `grunt-contrib-copy` target copies from `/src/main/webapp/` all HTML files, all images, and all fonts verbatim to `/src/main/webapp/dist/`.
* `ngAnnotate`: the [grunt-ng-annotate](https://github.com/mgol/grunt-ng-annotate) task allows for expressing [AngularJS dependency annotations](https://docs.angularjs.org/guide/di#dependency-annotation) [differently](https://www.npmjs.com/package/ng-annotate).
* `cssmin`: this [`grunt-contrib-cssmin`](https://github.com/gruntjs/grunt-contrib-cssmin) task will execute the previously generated `cssmin:generated` target (generated by `useminPrepare`). `useminPrepare`'s `/src/main/webapp/index.html` analysis will have `cssmin:generated` take file `/src/main/webapp/assets/styles/main.css` (previously generated during the `sass:server` target), css-minify it, and place it to `/.tmp/cssmin/assets/styles/main.css`... Also, the `index.html` analysis will take all Bower CSS dependencies, concatenate them to one bundle, minify that bundle, and place that minified bundle in and place it to `/.tmp/cssmin/assets/styles/vendor.css`.
* `autoprefixer`: this [grunt-autoprefixer](`https://github.com/nDmitry/grunt-autoprefixer`) task will execute the previously generated `autoprefixer:generated` target (generated by `useminPrepare`). This target takes the outputs from the previous usemin-css step target `cssmin:generated` and prefixes CSS properties with vendor prefixes. As `autoprefixer` is the last step in the usemin CSS pipeline, the final usemin CSS artifacts will land in the paths as specified with `useminPrepare.options.dest + $(build:css-annotations-found-in-index.html)`: `/src/main/webapp/dist/assets/styles/main.css` and `/src/main/webapp/dist/assets/styles/vendor.css`.
* `uglify`: this [`grunt-contrib-uglify`](https://github.com/gruntjs/grunt-contrib-uglify) task will execute the previously generated `uglify(js):generated` target (generated by `useminPrepare`). This target takes the output from the previous usemin-js step target `concat:generated` and uglify-js-minifies it. As `uglify` is the last step in the usemin JS piepline, the final usemin JS artifacts will land in the paths as specified with `useminPrepare.options.dest + $(build:js-annotations-found-in-index.html)`: `/src/main/webapp/dist/scripts/app.js` and `/src/main/webapp/dist/scripts/vendor.js`.
* `rev`: this [grunt-rev](https://github.com/sebdeckers/grunt-rev) task uses *revving* to rename JS, CSS, image, and font files in the `/src/main/webapp/dist/` directory.
* `usemin`: this [grunt-usemin](https://github.com/yeoman/grunt-usemin#the-usemin-task) task investigates all HTML files within the `/src/main/webapp/dist/` directory (previously copied there during the `copy:dist` target execution). The task will find references to unconcatenanted, unrevved assets (JS, CSS, images), then replace these references with the concatenated single-bundles-and-revved filenames.
* `htmlmin`: this [`grunt-contrib-htmlmin`](https://github.com/gruntjs/grunt-contrib-htmlmin) task takes all `/src/main/webapp/dist/*.html` files and html-minifies them in-place.
[JHipster]: https://jhipster.github.io/
[Node.js]: https://nodejs.org/
[Bower]: http://bower.io/
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment