You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

3.4 KiB

Getting started

If you'd like to work on the Python code that processes files for Circlean, you should take a look at PyCIRCLean, specifically the script. To get started contributing to Circlean, first, fork the project and git clone your fork. Then, follow the instructions in to build an image. To make things easier, you can also download a prebuilt image as mentioned in the README, and then mount and make modifications to this image to test your changes.

The issue tracker

If you find a bug or see a problem with PyCIRCLean, please open an issue in the Github repo. We'll do our best to respond as quickly as possible. Also, feel free to contribute a solution to any of the open issues - we'll do our best to review your pull request in a timely manner. This project is in active development, so any contributions are welcome!


  • Timidity for playing midi files
  • Git for installing some Python dependencies
  • 7Zip for unpacking archives
  • ntfs-3g, exfat-fuse for mounting usb key partitions
  • Python 3 and pip for installing and running Python dependencies
  • Python3-lxml for handling ooxml and other Office files in
  • libjpeg-dev, libtiff-dev, libwebp-dev, liblcms2-dev, tcl-dev, tk-dev, and python-tk for various image formats (dependencies for pillow)
  • Exifread for file metadata
  • Pillow for handling images
  • Olefile, oletools, and officedissector for handling various Office filetypes
  • PyCIRCLean for main file handling code

Helper scripts

Use the scripts in shell_utils/ as examples - do not run them blindly as you will most probably have to change some constants/paths accordingly to your configuration.


  • uses qemu to chroot into a raspbian instance (.img or SD Card)
  • update the system, some configuration
  • create the user who will run the scripts, assign the proper sudo rights.
  • populate the content of the directory fs/ in the image, contains a sample of dd command to write the image on the SD card. NOTE: TAKE CARE NOT TO USE THE WRONG DESTINATION

Running the tests

  • If you've made changes to the shell scripts, start by installing and running Shellcheck.

  • To emulate the Raspberry Pi hardware for testing, we'll be using Qemu, an open source machine emulator. The "qemu" package available for Ubuntu/Debian includes all of the required packages (including qemu-system-arm) except for qemu-user-static, which must be installed separately.

    sudo apt-get install qemu qemu-user-static expect
  • Get the qemu kernel for the image you are using:
   pushd tests; wget; popd
  • Put some test data from tests/testFiles into tests/content_img_vfat_norm

  • Comment out the other tests in tests/ or populate those directories as well

  • Make sure to set the filename of the image and the kernel in tests/

  • Run the tests:

    sudo ./
  • If the image run processed images correctly but doesn't exit and unmount the images cleanly, look at tests/run.exp and make sure it's waiting for the string your qemu and kernel actually produce.