===============================================
Download and installation instructions for Cado
===============================================
Questions? Ask on the cado forum:
https://groups.google.com/forum/#!forum/cadolang
PREREQUISITE: we assume you have installed some version of perl >= 5.8,
and have the perl interpreter in your path:
$ perl --version
This is perl 5, version 26 ...
...
Cado is very portable and will run against perl 5.8 or later.
Some cado extension libraries may require additional perl modules, but the
base interpreter has no external perl dependencies.
After you have verified your perl installation, pick a port from the
following list. We will call it "$PORT":
{linux, cygwin, nt, macosx, solx86, solsparc}
NOTE: the nt distribution requires MKS/NT. The cygwin port is usually a
better option for windows.
Next, untar or unzip the distribution into a directory. We will call it
"$TOOLROOT". For example:
cd /tmp
tar xvf cado_macosx_1_112.tgz
export TOOLROOT
TOOLROOT=/tmp/cado_macosx_1_112
Set-up your environment to run Cado. For bash and posix shells:
export PERL_LIBPATH
export CG_TEMPLATE_PATH
PERL_LIBPATH="$TOOLROOT/lib/cmn"
CG_TEMPLATE_PATH=".;$TOOLROOT/lib/cmn/templates;$TOOLROOT/lib/cmn/templates/java"
PATH="$TOOLROOT/bin/${PORT}:$TOOLROOT/bin/cmn:$PATH
For tcsh/csh shells:
setenv PERL_LIBPATH "$TOOLROOT/lib/cmn"
setenv CG_TEMPLATE_PATH ".;$TOOLROOT/lib/cmn/templates;$TOOLROOT/lib/cmn/templates/java"
set path = ( $TOOLROOT/bin/$PORT $TOOLROOT/bin/cmn $path )
They try:
% cado -V
cado: Version 1.112, 01-Aug-2018.
If this works, you are all set up and ready to go.
-----
NOTES:
-----
o If you are running on another unix variant, pick the linux distribution
and recompile the crc binary (you can use any C compiler):
gcc -o $TOOLROOT/bin/$PORT/crc $TOOLROOT/bin/$PORT/src/crc.c
If you have any trouble with crc on your platform variant, recompile it.
Note that cado will still work without the compiled crc, by substituting a
perl implementation. However, some operations will be slower - primarily,
update operations, since cado uses crc to compare the newly generated
result against the previous version.
o Here is an instructive way to get the documentation:
cado -q
%readtemplate thedoc cgdoc.txt
%print $thedoc
^D (control-d or EOF to exit interactive interpreter)
If this doesn't work, then check your CG_TEMPLATE_PATH setting.
o To see the doc the old fashioned way:
cat $TOOLROOT/lib/cmn/templates/cgdoc.txt
The file cgdoc.txt is the best documentation currently. Keep it handy.
o There is also command line help: cado -help
============================================================================
Please feel free to email with any questions: russt (at) releasetools.org.
Or join the cadolang mailing list:
https://groups.google.com/forum/#!forum/cadolang
Twitter hashtag: #cadolang
Release date: 08/15/2018
============================
Version 1_112 Release Notes:
============================
-----------------
Language changes:
-----------------
o cado now allows dashes in variable names.
o added %redirect statement, which provides functionality to redirect stderr
and stdout.
o added %version statement, which reports the interpreter version.
----------------------
New standard operators:
----------------------
o implemented pure perl of :pwd :ls, :mkdir, :chdir, :rm, :rmtree, :ps
formerly, some of these ops called out to the shell.
o added :regressdiff operator for testing, which allows for IGNORE tokens.
o added :hextodec :dectohex operators to convert between base 16 & base 10.
----------------------------
New Libraries and Templates:
----------------------------
o Added new JSON operators, to simplify JSON document verification and
display.
The JSON cado library is not yet comprehensive. The following operators
are supported:
$jsonStr:isJson - 1 if $jsonStr is valid JSON, 0 otherwise
$jsonStr:ppJson - pretty-print a JSON string
o Added new JMESPATH operator to query JSON documents.
See: http://jmespath.org
CG_JMSEPATH_SPEC = <jmespath expression>
$jsonStr:jmespath - apply the JMESPATH expression to <jsonStr>
The :jmespath operator assumes you have a "jp" binary in your path.
You can override the default with CG_JMESPATH_PROCESSOR, e.g.
CG_JMESPATH_PROCESSOR = jp.py
There are several JMESPATH processors available - see:
http://jmespath.org/libraries.html
The golang processor is recommended:
https://github.com/jmespath/jp
--------------------------------
Updated Libraries and Templates:
--------------------------------
o Updated vmware library (vmw_ops.pl) by adding following new operators:
:vmw_searchfolder returns list of moids where inventory matches input pattern.
:vmw_gettemplates returns list of all vm templates or empty string.
:vmw_config_annotation retrieve config_annotation for a moid
:vmw_guest_family retrieve guest_family for a moid
:vmw_guest_id retrieve guest_id for a moid
:vmw_inventory_path retrieve inventory_path for a moid
:vmw_num_cpu retrieve number of cpu's for a moid
:vmw_memory_size_mb retrieve memory size for a moid
:vmw_path_name retrieve path_name for a moid
:vmw_datastore retrieve datastore name for a moid
----------
Bug fixes:
----------
o cado will now run on perl 5.26, which changes the semantics of curly
brackets in perl regular expressions. All tests pass against:
perl 5.16
perl 5.18
perl 5.20
perl 5.26
-----------
Usage Notes
-----------
o If you have cado scripts using regular expression specs, e.g.,
CG_SUBSTITUTE_SPEC, CG_MATCH_SPEC, etc., then you may need to update the
specs by escaping '{' and '}' chars with backslash ('\{' '\}').
Alternatively, use a perl releases prior to 5.26.
