Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Moodle Development kit: Difference between revisions

From MoodleDocs
(Created page with "Every developer creates simple tools to avoid repeating cumbersome and/or boring tasks, and that is precisely why MDK has been created: to pack all those useful tools in a portab...")
 
mNo edit summary
(20 intermediate revisions by 4 users not shown)
Line 7: Line 7:
= Typical workflows using MDK =
= Typical workflows using MDK =


To discover what MDK can do for you, here are a few common tasks it can achieve.
To discover what MDK can do for you, here are a few common tasks it can achieve. More on [https://github.com/FMCorz/mdk/wiki/Typical-workflows MDK's wiki].


== Installing a new instance ==
== Installing a new instance ==
Line 14: Line 14:


  mdk create -i -v 24 -e pgsql -r dev users
  mdk create -i -v 24 -e pgsql -r dev users
or the equivalent long form:
mdk create --install --version 24 --engine pgsql --run dev users


This is equivalent to doing:
These options include:
--install: launch the installation script after creating the instance
--engine: database engine to install the instance on (must be used with --install), default: mysqli
--version: version of Moodle create an instance of (default: 'master')
--run: scripts to run after installation (default: none)
 
More information about scripts is available here: https://github.com/FMCorz/mdk/tree/master/mdk/scripts
 
The above command is equivalent to doing:


  mkdir /dir/to/stable_24/moodle
  mkdir /dir/to/stable_24/moodle
Line 37: Line 47:
  # Login to Moodle
  # Login to Moodle
  # Create 10 students, 3 teachers and 3 managers
  # Create 10 students, 3 teachers and 3 managers
You also can specify the name of the instance using the --name or -n parameter. This is necessary to avoid name conflicts when trying to create same Moodle version with different database engines:
mdk create -i -v 24 -e mysqli -r dev users -n stable_24-mysql


== Fixing an issue ==
== Fixing an issue ==
Line 76: Line 90:
  php admin/tool/phpunit/cli/init.php
  php admin/tool/phpunit/cli/init.php
  phpunit
  phpunit
For executing only the testcases in a file you can use:
mdk phpunit -r -u repository/tests/repository_test.php


== Upgrading the instances ==
== Upgrading the instances ==
Line 92: Line 111:
  php admin/cli/upgrade.php --non-interactive --allow-unstable
  php admin/cli/upgrade.php --non-interactive --allow-unstable


= Features =


For a complete list of the commands MDK has to offer, read through the [https://github.com/FMCorz/mdk#command-list MDK README file]. For more detail about each command, simply run them with the flag '--help'.
== Executing behat tests ==


= Installation =
In order to get the instance ready for acceptance testing (Behat) and run the test feature(s):
mdk behat -r --tags=@core_completion


== Debian/Ubuntu ==
For running only one feature or specific scenario:


  sudo apt-add-repository ppa:2x1cq-fred-7nqa6/ppa
  mdk behat -r -n "Name of the feature/scenario"
sudo apt-get update
sudo apt-get install moodle-sdk
sudo mdk init
# The next line prevents your from logging out and in again.
sudo su `whoami`


== Mac OS ==
= Features =


brew tap danpoltawski/homebrew-mdk
For a complete list of the commands MDK has to offer, read through the [https://github.com/FMCorz/mdk#command-list MDK README file] and the [https://github.com/FMCorz/mdk/wiki MDK wiki]. For more detail about each command, simply run them with the flag '--help'.
brew install moodle-sdk
sudo mdk init


Installing MDK on Mac requires Homebrew; to install it use the following command.
= Installation =


ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"
Please follow the instructions from the [https://github.com/FMCorz/mdk#installation README file].


== Windows ==
Note: When you install MDK, you will be asked for the following information (with default responses indicated in square brackets):


MDK has been tested on Windows, but it doesn't work yet. It will possibly work after a few minor bug fixes.
*  What user are you initialising MDK for? [default - your current username]
*  What is the DocumentRoot of your virtual host? [~/www] <- '''See note below'''
*    Where do you want to store your Moodle instances? [~/moodles] <- This can be in your home directory (the default) because a symlink will be created using DocumentRoot
*    What is your Github username? (Leave blank if not using Github)
*    What is your MySQL user? [root]
*    What is your MySQL password? [root]
*    What is your PostgreSQL user? [root]
*    What is your PostgreSQL password? [root]


== Manual ==
'''Note''': By default, MDK will install instances to your home directory. A symlink will be created from your DocumentRoot to the install location. You will need to either change the DocumentRoot of your host to the path to your html root directory, e.g. /var/www/html, or create a file in /etc/httpd/conf.d/moodlehq.conf that configures a virtual host in your home directory.


Please follow the instructions from the [https://github.com/FMCorz/mdk#manual-installation README file].
'''Also note that you may need to set the path variable to null:'''
mdk config set path ""
 
= Upgrading MDK =
Every Moodle release, a new version of MDK is also being released in order to prepare for the development of the next Moodle version. To upgrade MDK:
# Update all of the Moodle instances: ''mdk update --all''
# Check out the master branch for all of your master instances, e.g. in your stable_master branch: ''git checkout master''
# Upgrade MDK
## Via pip: ''sudo pip install moodle-sdk --upgrade''
## Via Homebrew: ''brew upgrade moodle-sdk''
# Run MDK doctor to fix its ''masterBranch'' configuration. ''mdk doctor --fix --masterbranch''
# Run MDK doctor to check the master instances. ''mdk doctor --all''
#* If you don't see an error saying something like “stable_master is on branch master instead of MOODLE_XX_STABLE”, then you're all good. Otherwise, do a hard reset your master instances:
mdk update -c
cd ~/moodles/[integration/stable]_master
git checkout master
git fetch `mdk config show upstreamRemote`
git reset --hard `mdk config show upstreamRemote`/master


= The MDK Suite =
= The MDK Suite =
Line 136: Line 173:


This is an authentication plugin for Moodle 2.x, which not only creates the user if it does not exist in the database yet, but also enrols it as a student, teacher or manager in all the available courses. More information about this plugin is available on the [https://github.com/FMCorz/moodle-auth_mdk public repository].
This is an authentication plugin for Moodle 2.x, which not only creates the user if it does not exist in the database yet, but also enrols it as a student, teacher or manager in all the available courses. More information about this plugin is available on the [https://github.com/FMCorz/moodle-auth_mdk public repository].
[[Category:Developer tools]]

Revision as of 01:33, 21 May 2019

Every developer creates simple tools to avoid repeating cumbersome and/or boring tasks, and that is precisely why MDK has been created: to pack all those useful tools in a portable way across systems. Initially developed in Bash, the project moved to Python to avoid dealing with inconsistencies between Unix platforms, and eventually to support Windows.

Key concept

The most important concept of MDK is that it works with Moodle instances. An instance of Moodle is a directory in which you have checked out a particular version together with a database using a specific database engine. This means that if you want to work on Moodle 2.3 and 2.4, using both MySQL and PostgreSQL, you will have four separate instance directories. This choice was made because it is the safest, clearest, and most straightforward solution.

Typical workflows using MDK

To discover what MDK can do for you, here are a few common tasks it can achieve. More on MDK's wiki.

Installing a new instance

Say we need to create a new instance of Moodle 2.4 and install it with PostgreSQL. We also want the instance to be ready for development with appropriate config settings. We also want to create a bunch of user accounts.

mdk create -i -v 24 -e pgsql -r dev users

or the equivalent long form:

mdk create --install --version 24 --engine pgsql --run dev users

These options include:

--install: launch the installation script after creating the instance
--engine: database engine to install the instance on (must be used with --install), default: mysqli
--version: version of Moodle create an instance of (default: 'master')
--run: scripts to run after installation (default: none)

More information about scripts is available here: https://github.com/FMCorz/mdk/tree/master/mdk/scripts

The above command is equivalent to doing:

mkdir /dir/to/stable_24/moodle
mkdir /dir/to/stable_24/moodledata
ln -s /dir/to/stable_24/moodle /var/www/stable_24
git clone git://git.moodle.org/moodle.git /dir/to/moodle
cd /dir/to/stable_24/moodle
php admin/cli/install.php --wwwroot="http://localhost/stable_24" --dataroot=/dir/to/stable_24/moodledata --dbtype=pgsql --dbname=stable24 --dbuser=root --dbpass=root --dbhost=localhost --fullname="Stable 24 PostgreSQL" --shortname=stable_24 --adminuser=admin --adminpass=test --allow-unstable --agree-license --non-interactive
vim config.php
# Add the following settings:
# - $CFG->sessioncookiepath: /stable_24/
# - $CFG->debug: DEBUG_DEVELOPER
# - $CFG->debugdisplay: 1
# - $CFG->passwordpolicy: 0
# - $CFG->perfdebug: 15
# - $CFG->debugpageinfo: 1
# - $CFG->allowthemechangeonurl: 1
# - $CFG->cachejs: 0
# - $CFG->yuicomboloading: 0
# Include FirePHP Core
# Login to Moodle
# Create 10 students, 3 teachers and 3 managers

You also can specify the name of the instance using the --name or -n parameter. This is necessary to avoid name conflicts when trying to create same Moodle version with different database engines:

mdk create -i -v 24 -e mysqli -r dev users -n stable_24-mysql

Fixing an issue

mdk fix 12345
# Committing your patch
mdk push -t

This is equivalent to doing:

git branch --track MDL-12345-24 origin/MOODLE_24_STABLE
git checkout MDL-12345-24
# Committing your patch
git push github MDL-12345-24
# Editing the tracker issue to add
# - Git repository URL
# - Git branch for 2.4
# - Git compare URL for 2.4

Peer reviewing a patch

Here we want to pull a patch from a tracker issue into a new testing branch, and then run the PHPUnit tests.

mdk pull 12345 -t
mdk phpunit -r

This is the equivalent to doing:

cd /dir/to/stable_24/moodle
git branch --tracker MDL-12345-24-test MOODLE_24_STABLE
git checkout MDL-12345-24-test
git pull git://github.org/Someone/moodle.git MDL-12345-24
# And now the PHPUnit part
mkdir /dir/to/stable_24/moodledata_phpu
vim config.php
# To add
# - $CFG->phpunit_dataroot = '/dir/to/stable_24/moodledata_phpu';
# - $CFG->phpunit_prefix = 'phpu_';
php admin/tool/phpunit/cli/init.php
phpunit

For executing only the testcases in a file you can use:

mdk phpunit -r -u repository/tests/repository_test.php


Upgrading the instances

Say we need to upgrade our instances, as a new weekly release has just been made available.

mdk upgrade -u --all

This is the equivalent to doing:

# For each instance of Moodle...
cd /dir/to/stable_24/moodle
git checkout MOODLE_24_STABLE
git fetch origin
git reset --hard origin/MOODLE_24_STABLE
php admin/cli/upgrade.php --non-interactive --allow-unstable


Executing behat tests

In order to get the instance ready for acceptance testing (Behat) and run the test feature(s):

mdk behat -r --tags=@core_completion

For running only one feature or specific scenario:

mdk behat -r -n "Name of the feature/scenario"

Features

For a complete list of the commands MDK has to offer, read through the MDK README file and the MDK wiki. For more detail about each command, simply run them with the flag '--help'.

Installation

Please follow the instructions from the README file.

Note: When you install MDK, you will be asked for the following information (with default responses indicated in square brackets):

  • What user are you initialising MDK for? [default - your current username]
  • What is the DocumentRoot of your virtual host? [~/www] <- See note below
  • Where do you want to store your Moodle instances? [~/moodles] <- This can be in your home directory (the default) because a symlink will be created using DocumentRoot
  • What is your Github username? (Leave blank if not using Github)
  • What is your MySQL user? [root]
  • What is your MySQL password? [root]
  • What is your PostgreSQL user? [root]
  • What is your PostgreSQL password? [root]

Note: By default, MDK will install instances to your home directory. A symlink will be created from your DocumentRoot to the install location. You will need to either change the DocumentRoot of your host to the path to your html root directory, e.g. /var/www/html, or create a file in /etc/httpd/conf.d/moodlehq.conf that configures a virtual host in your home directory.

Also note that you may need to set the path variable to null:

mdk config set path ""

Upgrading MDK

Every Moodle release, a new version of MDK is also being released in order to prepare for the development of the next Moodle version. To upgrade MDK:

  1. Update all of the Moodle instances: mdk update --all
  2. Check out the master branch for all of your master instances, e.g. in your stable_master branch: git checkout master
  3. Upgrade MDK
    1. Via pip: sudo pip install moodle-sdk --upgrade
    2. Via Homebrew: brew upgrade moodle-sdk
  4. Run MDK doctor to fix its masterBranch configuration. mdk doctor --fix --masterbranch
  5. Run MDK doctor to check the master instances. mdk doctor --all
    • If you don't see an error saying something like “stable_master is on branch master instead of MOODLE_XX_STABLE”, then you're all good. Otherwise, do a hard reset your master instances:
mdk update -c
cd ~/moodles/[integration/stable]_master
git checkout master
git fetch `mdk config show upstreamRemote`
git reset --hard `mdk config show upstreamRemote`/master

The MDK Suite

Some other tools have been developed using the name MDK as they are considered as part of the development kit but are often mistaken with the real MDK. The real MDK is the command line tool described above.

MDK Browser Extension

Available for both Firefox and Chrome, this is a browser extension that allows quick access to useful user-scripts. The scripts add functionality to Moodle.org, Moodle Tracker and your Moodle instances. You can find more information about it on its public repository.

MDK Authentication

This is an authentication plugin for Moodle 2.x, which not only creates the user if it does not exist in the database yet, but also enrols it as a student, teacher or manager in all the available courses. More information about this plugin is available on the public repository.