The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Enbld-0.7030
River stage zero No dependents
1 ++
/ Enbld::Tutorial

NAME

Enbld::Tutorial - Tutorial for Enbld

GRAMMAR OF DSL

At Enbld, DSL for exclusive use defines the conditions of the software installation. Here, explain the grammar of the DSL.

THE EXAMPLE OF CONDITIONS SCRIPT

  #!/usr/bin/perl

  use strict;
  use warnings;

  use lib "$ENV{HOME}/.enbld/extlib/lib/perl5/";

  use Enbld;

  enbld 'mydevenv' => build {

      target 'git' => define {
          version 'latest';
      };

  };

FUNDAMENTAL ARCHITECTURE

  • Specify system perl to shebang

      #!/usr/bin/perl

    Enbld must be ran from system perl. Therefore, please be sure to specify the path to system perl as shebang>.

  • Must set 'use strict' and 'use warnings'

      use strict;
  use warnings;

    For modern perl scirpt, that must use.

  • Set path to Enbld's module by using lib pragma

      use lib "$ENV{HOME}/.enbld/extlib/lib/perl5/";

    Since Enbld's modules (Enbld.pm etc.) are installed to $HOME/.enbld/extlib/lib/perl5/, specify a path by a 'lib' pragma so that the modules can be loaded.

  • Load Enbld module

      use Enbld;

    Enbld module exports DSL's methods.

THE FUNCTIONS FOR THE INSTALLATION OF THE SOFTWARE

It explains the functions which can be used for below by DSL of Enbld. All of these functionses are exported at the time point of "use Enbld".

Since DSL of Enbld is a perl-based, all the things that are not written here follow the grammar of perl.

enbld

  enbld 'mydevenv' => build {
      ...
  }

'enbld' is a functions which performs an installing the software.

The first arguments specifies an environmental name. If it is a string, it will not matter anything.

The second arguments is the code references which the 'build' functions returns.enbld builds a Software by running the code reference to which conditions were written.

build

'build' is a functions of only the returning code reference.

It is a functions of a raise sake about the readability as a DSL.

target

  target 'git' => define {
      ....
  };

'target' is a functions which defines the conditions of the installation for every software.

The first arguments specifies the name of a software. It is necessary to coincide the name of a software with the name displayed by enblder available.

The second Arguments is the code references which a 'define' functions returns. 'target' defines the conditions of installations by running the code reference to which written the conditions of the installation.

define

'define' is a functions of only the returning code reference.

It is a functions of a raise sake about the readability as a DSL.

version

  target 'perl' => define {
      version '5.18.1';
  };

'version' is a functions which specifies a version number to install. It specifies a version number as an arguments.

A list of the version which can install can check by enblder available [software name].

An error will occur the version number not existing is specified.

  target 'git' => define {
      version 'latest';
  };

Moreover, if it is specified as 'latest' at a version, Enbld will specify and install the latest version automatically. There is no required of looking for the latest version by yourself.

  target 'perl' => define {
      version 'development';
  };

In addition, by a part of softwares, you can specify the version under development.

For example, at perl, even version numbers show under a development, it can install the newest development version by specifying it as 'development'.

Refer to the document of each Definition modules for a more.

make_test

  target 'git' => define {
      version 'latest';
      make_test 1;
  };

'make_test' is a functions for running test code at building.

if the value which serves as a true by perl is specified as an arguments (except udnef, and zero and a null character string), it runs test code at building.

If a test goes wrong, a build will also go wrong.

Usually, this features is come by off.

modules

  target 'perl' => define {
      version 'latest';
      modules {
          'App::cpanminus' => 0,
          'Carton'         => 0,
      };
  };

'modules' is a functions which it uses to install a modules using the modules install features which a programming language prepares.

For example, in perl, call cpan and install a modules.

Specify a hash reference as an arguments. In a hash, specify a key for a module name, and a value for a zero.

In the future, a modules version can be due being specified now.

Refer to the document of each Definition modules for a more.

arguments

  target 'perl' => define {
      version 'latest';
      arguments '-Dusethreads';
  };

'arguments' is a functions which adds the arguments to the 'configure' script of each software.

The string specified by the arguments is handed over as it is.

annotation

  target 'perl' => define {
      version 'latest';
      arguments '-Dusethreads';
      annotation 'with thread support';
  };

'annotation' is a functions which carries out an add annotation.

Unlike the comments of a mere script, enblder freeze also reproduce annotation.

THE FUNCTIONS FOR THE CREATION OF THE CONFIGURATION FILE

  conf '.vimrc' => load {
      from 'https://raw.github.com/magnolia-k/vimrc/master/.vimrc';
  };

Enbld also has a features for it not only building each software, but creating the Configuration file (DOTFILES) of each software.

In the above-mentioned e.g., it download the configuration file for vim (.vimrc) from GitHub, and set to home directory.

Moreover, in Enbld, since correlation of an installable software and the filename of a configuration file does not check, you can arrange any configuration files.

conf

  conf '.vimrc' => load {
  ...
  };

'conf' is a functions for creating a configuration file.

The first arguments specifies the filename of a configuration file.

When a directory is attached and specified, it interpreted as follows.

  • Relative path

    A specified of a relative path will create a configuration file as a relative path from $HOME.

    For example, if it is specified as .module-starter/config, the configuration file "config" will be created by $HOME/.module-starter/config.

  • Absolute Path

    A specified of an absolute path will create a configuration file on the path.

    For example, if it is specified as /path/to/.module-starter/config, the configuration file "config" will be created by /path/to/.module-starter/config.

    However, be careful of an access permission.

In addition, as long as a 'conf' functions is in the code reference specified as the arguments of the 'build' function, it may describe it anywhere.

  enbld 'mydevenv' => build {
      target 'vim' => define {
          version 'latest';

          conf '.vimrc' => load {
              from 'https://raw.github.com/magnolia-k/vimrc/master/.vimrc';
          }; # -> It's OK

      };

      conf '.bashrc' => set {
          content 'export PATH=$HOME/.enbld/bin:PATH';
      }; # -> It's also OK
  };

The second arguments is functionses which specify where Enbld acquire a configuration file from.

load

  conf '.vimrc' => load {
      from 'https://raw.github.com/magnolia-k/vimrc/master/.vimrc';
  };

Enbld download a configuration file from url specified by the arguments of the from functions.

An arguments is a code reference.

Enbld do nothing, when the files of the same content already exists. Even if a files exists, when the contents differ, Enbld change the filename of the existing files, and Enbld create a files as specified.

set

  conf '.bashrc' => set {
      content 'export PATH=$HOME/.enbld/bin:PATH';
  };

Enbld create a configuration file by the content specified by the arguments of the 'content' functions.

An arguments is a code reference.

Enbld do nothing, when the files of the same content already exists. Even if a files exists, when the contents differ, Enbld change the filename of the existing files, and Enbld create a files as specified.

copy

  conf '.vimrc' => copy {
      from '/path/to/.vimrc';
  };

Enbld copy and create a configuration file from the files specified by the arguments of the 'from' function.

An arguments is a code reference.

Enbld do nothing, when the files of the same content already exists. Even if a files exists, when the contents differ, Enbld change the filename of the existing files, and Enbld create a files as specified.

from

A 'from' functions is a functions which specifies the get origin of a configuration file.

Specify url or a full path as an arguments.

content

  conf '.vimrc' => set {
      content 'syntax on';
  };

A 'content' functions is a functions which specifies the content of a configuration file.

  conf '.wgetrc' => load {
      from 'http://xxx.xxx.xxx/.wgetrc';

      content 'proxy_user = user';
      content 'proxy_passwd = PassWord';
  }

Enbld can also add a postscript to the downloaded files using a 'content' Functions.

to

  conf 'filerc' => set {
    to "$ENV{HOME}/fileconfig";
    content 'setting string';
  };

'to' functions is a functions which specifies the deployment place of a configuration file.

Even when only a filename is specified as the arguments of a 'conf' functions, Enbld can control a deployment location by specifying a directory as to functions freely.

OPTIONS OF THE CONDITIONS SCIRPT

The conditions script can take some optionals. Here, explained the optional.

test

  $ ./conditions.pl --test

  $ ./conditions.pl -t

Option 'test' execute test at the installation.

force

  $ ./conditions.pl --force

  $ ./conditions.pl -f

Option 'force' installs all software also including an installed software by force.

deploy

  $ ./conditions.pl --deploy /path/to/install/

  $ ./conditions.pl -d /path/to/install/

Option 'deploy' specifies the installation location of the script which the condition script defined.

However, the release check of the new version of the software installed by 'deploy' is not made.

OTHER TOPICS

'.enbld' DIRECTORY COMPOSITION

'.enbld' directory has the following composition.

 $HOME/.enbld --+
                |
                +-- bin/         executable commands (symbolic links)
                |
                +-- lib/         library files       (symbolic links)
                |
                +-- include/     include files       (symbolic links)
                |
                +-- man/         man files           (symbolic links)
                |
                +-- share/       shared filed        (symbolic links)
                |
                +-- extlib/      Enbld's module files (e.g. lib/Enbld.pm)
                |
                +-- dists/       downloaded software' archivefiles
                |
                +-- etc/         other various files
                |
                +-- build/       software' build directory
                |
                +-- depository/  installed software' compornents files
                |   |
                |   +-- Software A
                |   |   |
                |   |   +-- version 1
                |   |   |
                |   |   +-- version 2
                |   |   |
                |   |
                |   +-- Software B
                |   |   |
                |   |   +-- version 1
                |   |   |
                |
                +--conf/         Enbld's configuration file
                |
                +--log/          Enbld's log files

Enbld installs software to $HOME/.enbld/depository/[Software Name]/[Version]/ and creates symbolic links to $HOME/.enbld/bin, $HOME/.enbld/lib, and so on. Therefore, it can change now easily a newer version.

SEE ALSO

Enbld

enblder

WEB SITE

https://github.com/magnolia-k/Enbld

http://code-stylistics.net/enbld

ISSUE REPORT

https://github.com/magnolia-k/Enbld/issues

COPYRIGHT

copyright 2013- Magnolia <magnolia.k@me.com>.

LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.