nik/FreedomBox
1
0
Fork 0
mirror of https://github.com/freedombox/FreedomBox.git synced 2026-05-27 10:44:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

HACKING: Update with instructions for multiple OSes

Browse Source 
- Add instructions on how to install Git, Vagrant and VirtualBox for other OSes.
  Instructions for other OSes are untested by me.

- Add instruction to checkout the source code.

- Remove instructions for installing on the host machine, these have not been
  tested for a while and could lead to confusion. 'setup.py develop' option is
  not being used anymore.

- Installing firefox using apt provides a sufficient version of functional
  tests. Simplify the instructions.

- Update functional tests instructions to use the '-m' mark option instead of of
  '-k' keyword.

Signed-off-by: Sunil Mohan Adapa <sunil@medhas.org>
Reviewed-by: James Valleroy <jvalleroy@mailbox.org>
This commit is contained in:
Sunil Mohan Adapa 2019-11-09 15:29:07 -08:00 committed by James Valleroy
parent 3809051760
commit 190a82e9e8
No known key found for this signature in database
GPG Key ID: 77C0C75E7B650808
1 changed files with 81 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
HACKING.md
View File

@ -1,5 +1,51 @@
# Hacking # Hacking
## Requirements for Development OS
FreedomBox is built as part of Debian GNU/Linux. However, you don't need to
install Debian to do development for FreedomBox. FreedomBox development is
typically done on a Virtual Machine. You can work on any operating system that
can install latest versions of Git, Vagrant and VirtualBox.
### For Debian GNU/Linux and Derivatives
1. Install Git, Vagrant and VirtualBox using apt.
```
$ sudo apt install git virtualbox vagrant
```
### For Other GNU/Linux Distributions or *BSDs
1. Install Git, Vagrant and VirtualBox using your favourite package manager.
### For macOS
1. Install [Brew](https://brew.sh/).
2. Install Git, Vagrant and VirtualBox using Brew.
```
brew install git
brew cask install vagrant
brew cask install virtualbox
```
### For Windows
1. Install [Git](https://git-scm.com/download/windows),
[VirtualBox](https://www.virtualbox.org/wiki/Downloads) and
[Vagrant](https://www.vagrantup.com/downloads.html) from their respective
download pages.
2. Tell Git to use Unix line endings by running the following in Git Bash.
```
git config --global core.autocrlf input
```
3. Run all the following commands inside Git Bash.
## Setting Up Development Environment Using Vagrant ## Setting Up Development Environment Using Vagrant
Vagrant is a free software command line utility for managing the life cycle of Vagrant is a free software command line utility for managing the life cycle of
@ -9,10 +55,11 @@ FreedomBox development rather simple: You can edit the source code on your host
and immediately see the effects in the running VM. The entire setup is automatic and immediately see the effects in the running VM. The entire setup is automatic
and requires about 4.5 GB of disk space. and requires about 4.5 GB of disk space.
1. Install Vagrant and VirtualBox: 1. Checkout FreedomBox Service (Plinth) source code using Git.
``` ```
$ sudo apt-get install virtualbox vagrant git clone https://salsa.debian.org/freedombox-team/plinth.git
cd plinth
``` ```
2. To download, setup, run, and configure a VM for FreedomBox development using 2. To download, setup, run, and configure a VM for FreedomBox development using
@ -23,92 +70,31 @@ and requires about 4.5 GB of disk space.
$ vagrant up $ vagrant up
``` ```
3. SSH into the running vagrant box with the following command: 3. SSH into the running vagrant box with the following command:
``` ```
$ vagrant ssh $ vagrant ssh
``` ```
4. Run the development version of Plinth from your source directory in the 4. Run the development version of FreedomBox Service (Plinth) from your source
virtual machine using the following command. This command continuously directory in the virtual machine using the following command. This command
deploys your code changes into the virtual machine providing a quick feedback continuously deploys your code changes into the virtual machine providing a
cycle during development. quick feedback cycle during development.
``` ```
$ sudo -u plinth /vagrant/run --develop $ sudo -u plinth /vagrant/run --develop
``` ```
Note: This virtual machine has automatic upgrades disabled by default. 5. If you have changed any system configuration files during your development,
you will need to run the following to install those files properly on to the
system and their changes to reflect properly.
## Manually Setting Up for Development
It is recommended that you use Vagrant to setup your development environment.
However, for some reason, you wish setup manually, the following tips will help:
1. Install dependencies as follows:
``` ```
$ sudo apt build-dep . $ sudo ./setup.py install
``` ```
``` Note: This development virtual machine has automatic upgrades disabled by
$ sudo apt install -y $(./run --list-dependencies) default.
```
Install additional dependencies by picking the list from debian/control file
fields Depends: and Recommends: for the package ''freedombox''.
2. Instead of running `setup.py install` after every source modification, run
the following command:
```
$ sudo python3 setup.py develop
```
This will install the python package in a special development mode. Run it
normally. Any updates to the code (and core package data files) do not
require re-installation after every modification.
CherryPy web server also monitors changes to the source files and reloads
the server as soon as a file is modified. Hence it is usually sufficient
to modify the source and refresh the browser page to see the changes.
2. FreedomBox Service (Plinth) also supports running without installing (as much
as possible). Simply run it as:
```
$ sudo ./run --develop
```
In this mode, FreedomBox Service (Plinth) runs from the working directory
without need for installation. The server restarts automatically when any
python file changes. The `plinth.conf` config file and the action
scripts of the working directory are used. It creates all that data and
runtime files in `data/var/*`.
More extensive debugging is enabled, Django security features are disabled
and module initialization errors will not pass silently.
*Note:* This mode is supported only in a limited manner. The following are
the unknown issues with it:
1. Help pages are also not built. Run `make -C doc` manually.
2. Actions do not work when running as normal user without `sudo` prefix.
You need to add `actions` directory to be allowed for `sudo` commands.
See `data/etc/sudoers.d/plinth` for a hint.
### Testing Inside a Virtual Machine
1. Checkout source on the host.
2. Share the source folder and mount it on virtual machine. This could be done
over NFS, SSH-fs or 'Shared Folders' feature on VirtualBox.
3. Run `setup.py develop` or `setup.py install` as described above on guest
machine.
4. Access the guest machine's FreedomBox web UI from host after setting bridging
or NATing for guest virtual machine.
## Running Tests ## Running Tests
@ -125,7 +111,7 @@ $ ./setup.py test
``` ```
To run a specific test function, test class or test module, use pytest filtering To run a specific test function, test class or test module, use pytest filtering
options. options. See pytest documentation for further filter options.
**Examples:** **Examples:**
@ -169,26 +155,27 @@ executed (red).
### Install Dependencies ### Install Dependencies
**For running tests in the VM** run `vagrant provision --provision-with tests`. #### For running tests inside the VM
Otherwise follow the instructions below.
Run `vagrant provision --provision-with test.
#### For running tests on host machine
Follow the instructions below to run the tests on host machine. If you wish
perform the tests on host machine, the host machine must be based on Debian
Buster (or later).
``` ```
$ pip3 install splinter $ pip3 install splinter
$ pip3 install pytest-splinter $ pip3 install pytest-splinter
$ pip3 install pytest-bdd $ sudo apt install python3-pytest-bdd
$ sudo apt install xvfb # optional, to avoid opening browser windows $ sudo apt install xvfb python3-pytest-xvfb # optional, to avoid opening browser windows
$ pip3 install pytest-xvfb # optional, to avoid opening browser windows $ sudo apt install firefox
``` ```
- Install the latest version of geckodriver. - Install the latest version of geckodriver. It is usually a single binary which
It's usually a single binary which you can place at /usr/local/bin/geckodriver you can place at /usr/local/bin/geckodriver . Geckodriver will use whichever
binary is named 'firefox' for launching the browser and interacting with it.
- Install the latest version of Mozilla Firefox.
Download and extract the latest version from the Firefox website and symlink the
binary named `firefox` to /usr/local/bin.
Geckodriver will then use whatever version of Firefox you symlink as
/usr/local/bin/firefox.
### Run FreedomBox Service ### Run FreedomBox Service
@ -225,17 +212,18 @@ $ py.test-3 --include-functional
``` ```
The full test suite can take a long time to run (more than an hour). You can The full test suite can take a long time to run (more than an hour). You can
also specify which tests to run, by tag or keyword: also specify which tests to run, by specifying a mark:
``` ```
$ py.test-3 -k essential --include-functional $ py.test-3 -m essential --include-functional
$ py.test-3 -m mediawiki --include-functional
``` ```
If xvfb is installed and you still want to see browser windows, use the If xvfb is installed and you still want to see browser windows, use the
`--no-xvfb` command-line argument. `--no-xvfb` command-line argument.
``` ```
$ py.test-3 --no-xvfb -k mediawiki --include-functional $ py.test-3 --no-xvfb -m mediawiki --include-functional
``` ```
## Building the Documentation Separately ## Building the Documentation Separately