Civix is a command-line tool for building CiviCRM extensions. It is distributed as part of CiviCRM-Buildkit.
- PHP 7.1.3+
- CiviCRM 5.0+ (installed from git http://github.com/civicrm)
- (For MAMP, WAMP, XAMPP, etc) PHP command-line configuration (http://wiki.civicrm.org/confluence/display/CRMDOC/Setup+Command-Line+PHP)
- (For CentOS/RHEL) Compatible version of libxml2 (totten#19)
Civix is distributed as a single, portable PHAR executable. As long as you have PHP-CLI properly configured, it should work as a simple download, e.g.
sudo curl -LsS https://download.civicrm.org/civix/civix.phar -o /usr/local/bin/civix
sudo chmod +x /usr/local/bin/civix
To upgrade an existing installation, simply re-download the latest civix.phar
.
To download the source tree and all dependencies, use git
and composer
, e.g.:
$ git clone https://github.com/totten/civix
$ cd civix
$ composer install
# Install composer
In a browser, visit http://getcomposer.org
Click on the download button.
Scroll down to Windows Installer and click on Composer-Setup.exe.
Choose Run when prompted.
# Install git
If you don't already have git, then in a browser visit http://git-scm.com/download/win.
Choose Run when prompted.
Leave all the defaults.
# Download civix
Decide where you want to install civix. You might want to put it in C:\Program Files, but you might get hassled about admin rights, in which case you can pick somewhere else, like C:\users\<your name>.
From the start menu choose All Programs -> Git -> Git Bash.
In the window that appears, type:
cd "/c/users/<your name>"
(note the forward slashes)
git clone git://github.com/totten/civix.git
exit
# Download dependencies
In windows explorer, navigate to C:\users\<your name> (or whereever you installed civix).
Shift-right-click on the civix folder.
Choose open command window here.
In the window that appears, type:
composer install
# Add civix to the PATH
Either temporarily add it:
set PATH=%PATH%;C:\users\<your name>\civix\bin
OR permanently:
Start Menu -> Control Panel -> System -> Advanced -> Environment Variables
The CiviCRM Developer Guide includes tutorials for building extensions
For reference documentation, civix supports a "--help" option. For example, to get reference materials about the "generate:page" command, run:
civix generate:page --help
If you are developing new changes to civix
and want to create custom build of
civix.phar
from source, you must have git
, composer
, and
box
installed. Then run:
$ git clone https://github.com/totten/civix
...
$ cd civix
$ composer install
...
$ which box
/usr/local/bin/box
$ php -dphar.readonly=0 /usr/local/bin/box build
If you want to run with the same versions of PHP+box that are used for official builds, then run:
nix-shell --run ./build.sh
Automated testing for civix
requires a live CiviCRM deployment -- where it can generate and install example extensions. The deployment
must be amenable to CLI scripting (eg civix
, cv
, civibuild
). You should set the environment variable CIVIX_WORKSPACE
to point to
a folder where we can safely fill+destroy extensions, such as:
export CIVIX_WORKSPACE=$HOME/buildkit/build/dmaster/web/sites/all/modules/civicrm/ext/civixtest
Tests are divided into a few areas:
- PHPUnit: End-to-end tests (
tests/e2e/**Test.php
) - PHPUnit: Unit tests (
src/CRM/CivixBundle/**Test.php
) - Snapshots: Library of example extensions (
tests/snapshots/*
)
Ensure that the CIVIX_WORKSPACE
is set before running phpunit. Also, ensure that there is clean database to test against.
For example:
export CIVIX_WORKSPACE=$HOME/buildkit/build/dmaster/web/sites/all/modules/civicrm/ext/civixtest
civibuild restore dmaster
phpunit8
The helper ./scripts/run-tests.sh
is a small wrapper which does the above.
Snapshots are extensions generated by historical versions of civix. The library of snapshots is used for E2E testing. Working with snapshots is also a handy way to evaluate patches and see how civix behaves. There are several scripts for working with snapshots.
export CIVIX_WORKSPACE=$HOME/buildkit/build/dmaster/web/sites/all/modules/civicrm/ext/civixtest
## Look at available snapshots
ls tests/snapshots/
## Run "civix upgrade" against the existing snapshots.
## Optionally, you may filter by name and increase verbosity.
./scripts/upgrade-snapshots.sh
./scripts/upgrade-snapshots.sh /entity34/
./scripts/upgrade-snapshots.sh /v22.10.2-entity34/
DEBUG=2 ./scripts/upgrade-snapshots.sh /v22.10.2-entity34/
## Review the output of "civix upgrade"
cd tests/snapshots/*/*v22.10.2-entity34*
less upgrade.log
zipdiff original.zip upgrade | colordiff | less -R
cd ../../../..
## Make new extensions with the current civix source-code.
## Save the snapshots for us to inspect.
./scripts/make-snapshots.sh --src
## As above, but also install and test the snapshots.
./scripts/make-snapshots.sh --src --test
## Make new snapshots and save for future reference.
./scripts/make-snapshots.sh --src --version v99.88
git add tests/snapshots/*v99.88*
## Remove any temporary data generated by the above.
./scripts/tidy-snapshots.sh