Skip to content

Local development

Jump to bottom
Greg Bowler edited this page Dec 16, 2022 · 10 revisions

This project, and the tools it's built on, are all open source, so anyone could follow this guide to get Trackshift running locally. In fact, that's encouraged! We'd love to hear how far people get, and if they fancy making any changes, pull requests are welcome.

Contents:

Apple Mac

PHP setup

This setup guide was tested on a 2012 Macbook Air.

You will need to install a massive Xcode update if you've never used your Mac for development. It'll take ages, and I don't think there's any way of getting around it, even if you never plan on using Xcode.

Install the package manager. Took about 5 mins.

  • https://brew.sh/ - copy paste installation into terminal
  • If needed, uninstall first - and I had to manually remove some dirs: rm -rf /usr/local/etc/php && rm -rf /usr/local/{.git,.gitignore,.travis.yml,CODEOF*,CONTRIBUTING*}

Actually install PHP! Took about 10 mins.

  • brew install php

Interestingly, because Mac doesn't have any package management system, brew is just a friendly wrapper to compiling the source code of PHP yourself.

Install dependency management tools

Composer is the tool used in the PHP world to install and manage third party dependencies, for example PHPUnit, Behat, WebEngine are all dependencies, and they too have their own list of dependencies. Composer handles installing them all for you.

NPM is the JavaScript ecosystem version of Composer, but it comes with a lot of baggage, so someone has kindly created "NVM" to manage the node versions, installing things locally so you can easily wipe the slate clean.

  • https://getcomposer.org/
  • Single-line composer install: curl https://raw.githubusercontent.com/composer/getcomposer.org/76a7060ccb93902cd7576b67264ad91c8a2700e2/web/installer | php && sudo mv composer.phar /usr/local/bin/composer && echo "export PATH=$HOME/.composer/vendor/bin:$PATH" >> ~/.zshrc # Note one old Macs that use Bash, this last file should be ~/.bash_profile instead
  • NVM (https://github.com/nvm-sh/nvm): curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash

Install tools using dependency management

In a new terminal (old one might not have been updated to see the new PATHs):

  • gt command: composer global require phpgt/gtcommand - gt is the command you use to interact with php.gt/webengine
  • npm: nvm install v18.12.1 NPM is the node package manager, used to install sass and webpack, which in turn manage any CSS and JS bundling required
  • sass, web pack: npm -g install sass webpack webpack-cli

Get the code

I use ~/Code for my root projects directory, then each org has its own subdir, like ~/Code/SuperHyperInstantFutureTime or whatever. Create the dir where you want to code to go, then:

  • git clone git@github.com:SuperHyperInstantFutureTime/trackshift
  • cd trackshift
  • composer install
  • gt run

Then go to http://localhost:8080/ in your browser.

Run tests

If you make any changes to the code, run the tests before committing anything:

  • Unit tests: ./vendor/bin/phpunit -c test/phpunit/phpunit.xml
  • Behavioural tests: ./vendor/bin/behat -c test/behat/behat.yml

Finally, have tremendous fun and try to leave a glowing memory through the work you do.

Linux

// TODO.

Windows

// TODO - nobody I know uses Windows, but it would be nice to document the process, just to ensure everything is built solidly and can run anywhere.

Clone this wiki locally