Skip to content

Latest commit

 

History

History
122 lines (86 loc) · 3.94 KB

develop.md

File metadata and controls

122 lines (86 loc) · 3.94 KB
Raw

Development

Prerequisites

Run

The main executable in the source-tree is ./bin/civix. You can call this from other folders.

For example, if your civix source is in $HOME/src/civix, and if your D7 site is in /var/www/example.com, then you might say:

cd /var/www/example.com/sites/default/files/civicrm/ext
$HOME/src/civix/bin/civix generate:module newmodule

Or:

export PATH="$HOME/src/civix/bin:$PATH"
cd /var/www/example.com/sites/default/files/civicrm/ext
civix generate:module newmodule

Build PHAR

TIP: For day-to-day development, you don't usually need to compile a PHAR. These steps are mostly useful if (a) you are specifically addressing an issue in the PHAR or (b) you are testing on a UF/CMS which is prone to dependency conflicts (such as D9/D10).

civix.phar is usually compiled inside a nix shell, i.e.

nix-shell --run ./scripts/build.sh

You may also compile it in another environment using git, composer, and box.

git clone https://github.com/totten/civix
cd civix
composer install
box compile

The output will be ./bin/civix.phar.

Tips

  • To match exact versions of the toolchain, consult shell.nix and the corresponding release of buildkit pkgs.
  • box may require updating php.ini.

Testing

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/*)

Testing: PHPUnit

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
phpunit9

The helper ./scripts/run-tests.sh is a small wrapper which does the above.

Testing: Snapshots

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