Source file tree builder.
setup a lsp ( livescript + stylus + pug ) watcher:
require! <[@plotdb/srcbuild]>
srcbuild.lsp {base: 'web', i18n: ..., logger: ...}
where
-
base
: root dir forsrc
andstatic
folders. default.
-
i18n
: i18n object. -
ignored
: files to be ignored. in anymatch-compatible definition.- by default ['.git']
-
logger
: optional. for logging output. useconsole.log
by default.-
sample logger with
pino
:require! <[@plotdb/srcbuild pino]> srcbuild.lsp({logger: pino({level: 'debug'})})
-
These fields will be passed to all customized builders. Additionally, configurations in builder-specific fields will lso be passed to corresponding customized builders. For example, bundle
field will be passed to bundle
builder:
srcbuild.lsp {bundle: { ... /* this will be passed to bundle builder */ }, ...}
For lsp
, there are 4 different builders:
-
lsc
: build*.ls
fromsrc/ls
tostatic/js
. -
stylus
: build*.styl
fromsrc/styl
tostatic/css
. -
pug
: build*.pug
fromsrc/pug
tostatic
. -
bundle
: bundlecss
andjs
files
See following sections for additional options in custom builders.
Extend base builder for a customized builder:
base = require("@plotdb/srcbuild").base
mybuild = (opt = {}) -> @init({srcdir: 'src', desdir: 'des'} <<< opt)
mybuild.prototype = Object.create(base.prototype) <<< {
is-supported: (file) -> return true
get-dependencies: (file) -> return []
build: (files) -> # build will be called if is supported.
}
with following user-defined functions:
-
is-supported(file)
: return true iffile
is supported by this builder, otherwise return false.-
file
: file name for file to be verified. Relative to cwd.
-
-
get-dependencies(file)
: return a list of files that this file depends on.-
file
: same asis-supported
-
-
build(files)
: should compile / generate target files of given file listfiles
.-
files
: a list of objects corresponding to files to be compiled, with following fields:-
file
: path of the file to be built, relative to cwd. -
mtime
: timestamp of the modified time of this file. may be modified time of its dependencies.
-
-
-
purge(files)
: should remove generated files corresponding to files listed infiles
.-
files
: same asbuild
.
-
-
resolve(file)
: return source file path for given target filefile
.- return null if the given target file can't be derived from any supported source files.
and the common options for init
are as following:
-
base
: root directory for srcbuild to run. -
srcdir
: directory for source files. should be relative tobase
. defaultsrc
if omitted. -
desdir
: directory for built files. should be relative tobase
. defaultstatic
if omitted. -
logger
: logger for log output. useconsole
if omitted. -
initScan
: default true. if true, run a directory scanning for files to build when adapter is initing.
check src/ext/lsc.ls
or src/ext/pug.ls
for example.
Except common options, each builder may support different options:
-
pug
:-
intlbase
: base dir to place i18n files. for example,intl
part of/intl/zh-TW/index.html
. defaultintl
. -
i18n
: an optional i18n object having the same interface withi18next
- when provided, enable i18n building with following additional features:
- source files will be built to multiple locations based on i18n config, such as
/intl/zh-TW/index.html
. - an additional function
i18n
will be available during pug compilation.-
i18n(text)
: translatetext
based on thei18n
object provided. -
language()
: return current language. ( e.g.,zh-TW
) -
intlbase(p, lng)
: return a path to givenp
, based on current i18n ( or specifiedlng
arg ) setup.- for example,
intlbase('link', 'kr')
may generate/intl/kr/link
, based on he base dir config.
- for example,
-
additionally, a pug filter
i18n
is also available, which can be used like:span:i18n translate this text
-
- source files will be built to multiple locations based on i18n config, such as
- when provided, enable i18n building with following additional features:
-
noView
: default false. when true, js view files ( generated toviewdir
) won't be built. -
viewdir
: default.view
. a directory for storing prebuilt pug files ( in .js format ) -
bundler
: default null. Auto packing will be possible only if this is provided. -
locals
: additional local variables for pug context when compiling.
-
-
lsc
:-
useGlslify
: default false. set to true if you need glslify of lsc files.- NOTE this is an experiment feature and may be removed ( move to standalone builder ) in the future.
-
-
bundle
: bundle options. includes:-
configFile
: json file storing bundle configuration. optional. -
relativePath
: use relative path for paths in config file. default false. possible values:-
false
: all files inconfigFile
are relative to current working directory. -
true
: all files inconfigFile
are relative to the directory containingbundle.json
- or, specific a path as the relative root.
-
-
manager
: block manager, optional. required for @plotdb/block bundling.- can be either an
block.manager
object, or ... - a function returning such object which accepts an object with following fields as parameter:
-
base
: the base dir of this bundle.
-
- can be either an
-
config
: bundle configuration in following format: { "css": { "name": [ ... list of files to bundle together ] }, "js": { ... } }
-
-
asset
: for copying asset files.-
ext
: array of file extensions to copy. default["png", "gif", "jpg", "svg", "json"]
-
These options are constructor options for corresponding builder, e.g., for pug builder:
new pugbuild({ i18n: ... })
When using shorthands like srcbuild.lsp(...)
, you can also specify corresponding option in scope, such as:
srcbuild.lsp({
base: '...', i18n: '...',
pug: {intlbase: '...'}
});
common options will be overwritten by scoped options.
Send adapters to watcher from getAdapter()
of each custom builders:
require! <[@plotdb/srcbuild/dist/watch @plotdb/srcbuild/dist/ext/pug]>
pugbuilder = new pug(...)
watcher = new watch({adapters: [pugbuilder.getAdapter]})
By default, watcher watches the current working directory. Change watcher behavior with following constructor options:
-
adapters
: array of adapters to use to handle file change events. -
ignored
: array of glob strings to ignore when watching for changes. by default[".git"]
. -
root
: directory, or array of directories to watch. by default["."]
. -
logger
: optional. logger object with logging functions such asinfo
,warn
anderror
.
use watch.demand(target-file)
to force rebuild by request. e.g.,
require! <[srcbuild]>
watch = srcbuild.lsp!
# this triggers rebuilding of `web/src/pug/index.pug` file.
watch.demand('web/static/index.html').then -> console.log "built."
target
to source
file mapping is done by resolve
function in custom builder, so to use on demand build, resolve
must be implemented.
use srcbuild.i18n
to quickly setup an i18next
object:
require! <[srcbuild]>
srcbuild.i18n(options)
.then (i18n) -> srcbuild.lsp {i18n}
options
is passed to i18next
init function. Additional fields in options
used by srcbuild.i18n
:
-
enabled
: true if i18n is enabled. default true
When i18n object is provided, i18n data can be used in pug files via i18n
function. e.g.,
div= i18n("my-key")
will show my-key
content defined in locale corresponding default.yaml
:
my-key: 這是我的鍵
To use a namespaced key, add :
before key. For example:
div= i18n("new-ns:another-key")
will access to another-key
in new-ns.yaml
. Be sure to add your namespace name in ns
field of i18n option:
"i18n": { ... "ns": ["default", "new-ns"] }
additionally, use intlbase
to wrap path with a i18n based relative path:
a(href=intlbase('/faq'))
When building, we extend Pug via plugins and filters to support more features.
Use @
to include files in modules:
include @/ldview/dist/ldview.pug
Use @static
to include files under static
folder:
include @static/assets/sample.pug
Other paths starting with @
are reserved and will cause error when used.
use script
and css
builtin mixins to load external script and css files:
+script({name: "module-name", version: "main", path: "somefile.js"})
+css({name: "module-name", version: "main", path: "somefile.js"})
where the fields of the parameters:
-
name
: module name -
version
: module version. defaultmain
, if omitted. -
path
: path of file to load. defaultindex.min.js
, if omitted. -
defer
: defer execution or not. defaulttrue
if omitted. -
async
: async loading or not. defaultfalse
if omitted.
By default the above script mixin generates a script tag pointing to files under /assets/lib/<name>/<version>/<path>
. You can customize the /assets/lib/
by calling libLoader.root(desiredPath)
.
Additionally, you can also use a list of modules:
+script([
{name: "module-a", version: "0.0.1", path: "somefile.js"},
{name: "module-b", version: "0.2.1", path: "another.js"},
{name: "module-c", path: "with-default-version.js"},
{name: "module-d", version: "with.default.path" },
{name: "with-defer-async", defer: false, async: true}
{name: "omit-everything"},
])
Use the second option object to specify additional parameters, including:
-
pack
: experimental deprecated default false. Enable auto packing or not.- if true, enable auto packing which trigger bundling automatically to a filename from md5 of all script urls.
- require
bundler
option in pugbuild constructor. - doesn't work with external urls.
- there are still issues about rebuilding and build from view.
- replaced by
bundle
filter, which runs in compile time.
-
min
: default true. When true, use minimized packed file with pack option.
Following formats and filters are supported:
-
lsc
: transpile content from livescript to JavaScript. -
stylus
: transpile content fromstylus
toCSS
. -
md
: transpile content frommarkdown
toHTML
. -
bundle
: bundle files including js, css or block. usage sample::bundle(options = {type: "block", files: [ { bid }, ... ]})
Following functions are added:
-
md(code)
: convertmarkdown
toHTML
. -
yaml(path)
: readyaml
file and return object. (tentative) -
yamls(path)
: read content ofyaml
files underpath
directory. (tentative)
There are some additional i18n
filters available if properly configured. See above for more information.
MIT