fabric-webbuilders is a collection of Fabric/Fabric3 tasks to easily build customized up-to-date versions of various HTML/JavaScript/CSS libraries. Currently supported are jQuery and Bootstrap. It also provides tasks to minify CSS and JavaScript.
The fabfile tasks in this package are just a frontend to the "build from source" instructions of the respective packages. This means that any command-line requirements for building the libraries from source have to be satisfied as well.
-
Install fabric-webbuilders:
pip install fabric-webbuilders
-
Add tasks to your
fabfile.py
:from fabric_webbuilders import BuildJqueryTask, BuildBootstrapTask build_jquery = BuildJqueryTask() build_bootstrap = BuildBootstrapTask()
-
Make sure you have npm installed, e.g. on Debian/Ubuntu, do:
sudo apt-get install npm # required on most Debian/Ubuntu systems sudo ln -s /usr/bin/nodejs /usr/local/bin/node
-
If you want to run the minification tasks, install clean-css and uglify-js:
npm install clean-css uglify-js
-
Start building the latest versions of jQuery and Bootstrap:
fab build_jquery build_bootstrap
fabric-webbuilders is designed to be very configurable. Every global and task-specific
configuration variable can be configured via your env
dictionary, either as
<library>_<option>
or just <option>
(the former has precedence), the tasks constructor or
via the command-line. For example, this would all configure were libraries get built:
from fabric.state import env
from fabric_webbuilders import BuildJqueryTask
# global build_dir for all libraries:
env['build_dir'] = 'build/'
# just for jquery, takes precedence over above option:
env['jquery_build_dir'] = 'build/jquery/'
# overrides any env variables:
build_jquery = BuildJquery_task(build_dir='build/jquery/')
and then executing:
fab build_jquery:build_dir=build/jquery/ # overrides env and task constructor
The following configuration options are avialable for all tasks:
-
build_dir
: The build-directory where the libraries are downloaded and build. The default is./<library>/
or$(VIRTUALENV_DIR)/build/<library>/
inside a virtualenv. Note thatenv['build_dir']
should not contain a library name, e.g. this would both build jquery inbuild/jquery/
:env['build_dir'] = 'build/' env['jquery_build_dir'] = 'build/jquery/'
-
origin
: The default origin to download the source from. For git-based tasks (jQuery and Bootstrap) this is their respective official git repositories. When overriden, it follow the same semantics as the default, e.g. a fork of the original repository. -
version
: The version to build. By default the latest version found is build.For git-based tasks this can be
HEAD
(which will build the current HEAD of the master branch), any treeish object (e.g. a tag or branch found in the git-repository) or a string starting with~
, which will build the latest release matching the version, e.g.build_jquery:version=~1
would build the latest jQuery 1.x version.Note that
env['version']
is ignored because it's populated by fabric. -
dest-dir
: Where to copy the built libraries after building.
Requires: git, npm, grunt (if excludes
are given), bower (jQuery <= 2.1.1)
fabric_webbuilders.BuildJqueryTask
clones/updates the official git repository and builds jQuery
with npm run build
or with grunt custom:<excludes>
if excludes are given.
Additional options;
exclude
: Excludes passed togrunt custom
to exclude parts of jQuery. Note that without this option there really isn't much difference to just downloading the latest minified version.
Requires: git, npm, grunt
fabric_webbuilders.BuildBootstrap
clones/updates the official git repository and builds
Bootstrap with grunt dist
.
The Gruntfile unfortunately doesn't allow much automatic customization (or it's at least not
documented) so if you pass a config.json
with the config
parameter, the task dynamically
rewrites less/variables.less
and less/bootstrap.less
and removes any unwanted javascript
(as
recommended).
This works for some common cases I've tested but might break in some cases. Please don't be shy to
file an issue.
Additional options:
config
: Use aconfig.json
generated by Bootstrap's customizer. This may be rather fragile, see above.
Minification tasks try to minimize the size of files (e.g. by removing unnecessary spaces, comments, etc.) and concatenate them to one single file that can be used in production environments.
Minification tasks do not use the env
dictionary, so you can configure them only using the
tasks constructor or on the command-line. All tasks share three command-line parameters:
-
dest
: The destination filename. -
files
: A list of files to minify. Due to the complexity of the parameter this can only be given as a constructor argument.Elements of the list can either be a simple string, in which case the file is used verbatim. If an element is a dictionary, it can contains a
src_dir
(default:.
) and a list of patterns (default:*.<pattern>
, e.g.*.css
for CSS minification). patterns are applied sequentially using Pythons fnmatch function. Patterns starting with a!
exclude files matching it. Patterns that end with os.sep can be used to skip directories, if the directory starts withos.sep
, only top-level directories are skipped. Example:from fabric_webbuilders import MinifyCSSTask minify_css = MinifyCSSTask(dest='minified.css', files=[ 'custom.css', # custom.css in the current directory { 'src_dir': 'static/dir1', # all *.css files in static/dir1, excluding *.min.css files. 'patterns': [ '*.css', # all files ending with '.css' '!*.min.css', # but exclude .min.css files '!subdir/', # skip any directory called 'subdir' '!/subdir?/', # skip any 'subdirA', 'subdirB' etc. at the root-level ], }, ])
-
verbose
: If a string starting withy
, output files that will be minified. Only useable via the command-line. -
options
: All other keyword arguments passed via the command-line are passed to the underlying tool. Must be a dictionary if passed via the constructor. By default, options starting with a-
are passed with the first-
stripped, single-letter options are prepended with a-
, other options are prepended with--
. If a non-empty string is passed as value, it is appended to the option string. Example:from fabric_webbuilders import MinifyCSSTask minify_css = MinifyCSSTask(files=['output.css'], dest=minified.css, options={ 'd': '', # Adds "-d" to the command-line 'verbose': '', # Adds "--verbose" to the command-line 'whatever': 'yes', # Adds "--whatever yes" to the command-line '-xyz': 'value', # Adds "xyz value" to the command-line '----xyz': 'value', # Adds "---xyz value" to the command-line (1st - stripped) })
The same can be given via the command-line:
fab minify_css:d=,verbose=,whatever=yes,-xyz=value,----xyz=value
Requires: clean-css
fabric_webbuilders.MinifyCSSTask
minifies CSS files using
clean-css.
Requires: uglify-js
fabric_webbuilders.MinifyJSTask
minifys JavaScript files using
UglifyJS2.
- Tasks for building jQuery and Bootstrap now build with the git repository as the true
working directory and that directories
node_modules/.bin
in the path. As a result, no longer have to locally install npm packages or take care of any PATH issues. - Minification tasks add
node_modules/.bin
to the path as well. - Python3 compatability fixes.
- Do not depend on any particular version of Fabric, so you can use Fabric3.
- Update GitPython dependency, do not list pip-tools in requirements.txt.
- Fix
dest_dir
parameter for bootstrap. - Add tasks to minify JavaScript and CSS.
- initial release, featuring builders for jQuery and Bootstrap