Installing the Bol Processor BP3 does not require any programming skills. Just use the installers for MacOS and Windows, or the installation scripts for Linux.
To use the Bol Processor BP3, you first need to install a local Apache HTML/PHP server on your desktop computer. This server runs a dedicated "web service" that is restricted to your computer. Only PHP (with its GD Graphics option) needs to be running, as no database is used by the Bol Processor interface.
On MacOS and Windows we recommend MAMP or XAMPP, both of which are Apache servers with pre-installed features. On Linux, XAMPP is the only choice. The procedure is given on the pages that show the installation of BP3 in the different systems, see below.
Once you've installed MAMP or XAMPP, installing Bol Processor is almost a one-click process.
MacOS users can quickly do the installation using an installer called BolProcessorInstaller.pkg. Follow instructions on this page.
Windows users can quickly do the installation using an installer called BolProcessorInstaller.exe. Follow instructions on this page.
Linux users can quickly do the installation using dedicated scripts. Follow instructions on this page.
👉 Once you've installed the Bol Processor BP3, use this page to familiarise yourself with how to use it.
The file structure of your installation
👉 Only for geeks!
Let us assume that your installation was successful. It created a "htdocs/bolprocessor" folder.
The file structure inside this folder is shown on the left. There is nothing related to Bol Processor outside of this folder.
This image includes "bp" which is the compiled version of the BP3 console for MacOS. The same is called "bp.exe" in Windows and "bp3" in Linux.
The "temp_bolprocessor" and "my_output" folders are automatically created when the interface is run. The contents of the "temp_bolprocessor" folder is cleared of all files/folders older than 24 hours.
Another folder called "midi_resources" is also created to store the settings for the real-time MIDI input and output ports.
Two additional folders, "csound_resources" and "tonality_resources", are created by the installation and filled with data shared by all projects.
Running the interface will also create "BP2_help.html" in the "php" folder using "BP2_help.txt" as its source.
The "ctests" folder — which we call a workspace — contains sample material used to check the operation of Bol Processor and to illustrate some musicological issues. It is updated by the installation scripts each time you upgrade to a new version.
If you create new material in the "ctests" workspace it won't be deleted by upgrades. However, if you modify files that come from the distribution, they will revert to the current distribution version on each upgrade. It is therefore a good idea to keep a copy of the "ctests" folder, as you are likely to modify some of its data files while using the program. You may want to restore the original versions later. You can also create your own workspaces (in tree structures) using either the BP3 interface or your computer's file manager.
A one-click notarized installer of Bol Processor BP3 is available. It is called "BolProcessorInstaller.pkg" and it can be downloaded from here (unique location).
Geeks may prefer an equivalent method using a script included in this package, see below.
This installer (or the script) is used for both initial installation and updates. Each time you run it, it will download the latest versions of the BP3 console source files, the interface PHP files and the sample set contained in the 'ctests' folder. Data, grammars and scripts that you've created will not be deleted. However, if you have modified files in the 'ctests' folder, they will be reverted to the current distribution version.
Install MAMP or XAMPP
If you try to run the installer of Bo Processor, it will first check that a local Apache server (MAMP or XAMPP) has been installed. Both are suitable since the Bol Processor interface contains exclusively HTML, PHP and JavaScript code. No database is required.
Don't try the virtual machine version of XAMPP! It won't work on Macs with M1 chips (and above). Use the native installer.
if you choose the (free) MAMP version, both MAMP and MAMP PRO will be installed, and the interface will occasionally prompt you to "upgrade" to MAMP PRO. But you don't need it for the Bol Processor!
For MAMP, the "htdocs" folder is in "Applications/MAMP". For XAMPP, it is in "Applications/XAMPP/xamppfiles".
If you want Apache to start automatically when you start your computer, this process is easy with MAMP. For XAMPP, you can create a startup script.
➡ You will not be able to run both MAMP/MAMP PRO and XAMPP Apache servers at the same time if they use the same ports. This wouldn't be a good idea anyway…
MAMP PRO
Below are instructions for rich people running MAMP PRO.
The MAMP PRO main page on MacOS (version 5.7)
Launch MAMP PRO from the Applications folder.
In the MAMP main window, click the Apache Enable button (see image). No need for MySQL.
The image shows the default settings for PHP, which is started with Apache.
In case of trouble, check the settings for ports (see image) and of hosts (general and Apache).
XAMPP
Open the XAMPP folder in the Applications folder and launch manager-osx.app as shown below.
The XAMPP main page will appear. Click on the Manage Servers tab, then select Apache Web Server and click Configure. This is necessary to set up the port to any value except "80" (or except "8888" in case you are also running MAMP). Suggestion: set it to "81". Then click the Start button. If there is no conflict with the ports, Apache will show up as "running":
The XAMPP folder (in the Applications folder on a Mac) and the XAMPP main page
Once Apache is running, you can click on the Welcome tag and the Go to Application button. This should display a (local) page about XAMPP in the path http://localhost/dashboard. Both the dashboard and bolprocessor folders will be located in the Applications/XAMPP/xamppfiles/htdocs folder.
Install the Bol Processor
After installing MAMP or XAMPP, you can run the installer "BolProcessorInstaller.pkg" or the "install_bolprocessor.sh" script. Both are equivalent.
Using the installer
Download "BolProcessorInstaller.pkg" from here and double-click it.
This installer has been notarized, which means it contains information that allows Apple to certify its validity.
An equivalent method is to run the "install_bolprocessor.sh" script found in the "macos-scripts" folder downloaded here. This makes it possible to understand each step of the installation and possibly suggest improvements.
After downloading "macos-scripts.zip", open the Terminal and type:
cd Downloads unzip -qo macos-scripts.zip cd macos-scripts sudo ./install_bolprocessor.sh
Installation issues
If the installer (or the script) does not find a "htdocs" folder created by MAMP or XAMP, it will stop the installation, warning you that one of them should be installed. In case both MAMP and XAMPP are installed — a bad idea! — the installer will choose MAMP.
Compile the 'bp' console
Now, assuming that the installation was successful, start MAMP or XAMPP and point your browser to localhost/bolprocessor/php/. This will display the home page of the Bol Processor.
If you see this frame in the image at the top right of the page, your life will be easy! All you have to do is click on the link to compile the console, which will take a minute or two.
If you don't see the link to compile, and instead a mention that 'gcc' is not responsive, things are bad! You are probably using an obsolete version of MacOS. You may need to install the command line developer tools in OS X (explanations) or the Xcode toolkit on your machine.
Install Csound
Csound is not required to run the Bol Processor, as you can work with MIDI files and real-time MIDI. However, it will give you access to a different approach to sound synthesis.
A frame asking for a correction of the path to Csound
The BP3 interface should be able to figure out the location of "csound" and fix its path accordingly. If it does not respond, you will be asked to change the path and perhaps the name of the Csound console (see image).
To update the Bol Processor console, its PHP interface and examples (the contents of the "ctests" folder), simplyrerun "BolProcessorInstaller.pkg". Using the latest version is safe!
The installer will download and install current versions of the software and data. It will delete the compiled "bp" console and prompt you to recompile it (with a single click).
Updating will not modify or delete any data you have created in the "ctests" folder or outside it. However, if you have modified a sample file without changing its name, it will be reverted to its distribution version.
The installer will also preserve the "_settings.php" file (if it exists), which contains your project settings.
Security
You are right to be concerned about security. Can you be sure that you have downloaded the correct version of "BolProcessorInstaller.pkg"? Normally yes, it is safe, because this installer has been notarized.
The size of the "BolProcessorInstaller.pkg" file is exactly 19966 bytes and its MD5 is 806a83f72daf1abd22436555abc2cc8b. You can calculate the MD5 checksum on this page. These numbers will indeed be subject to change with the release of new versions of the installer. Current version: 28 October 2024.
Geeks may want to customise it for their own use. Just download this folder which contains the script files (install_bolprocessor.sh and postinstall) along with instructions on how the installer has been built.
For readers not conversant with Unix shell scripts, the following is a description of the process in human language:
Check that an Apache server MAMP or XAMPP is installed by finding either MAMP/htdocs or xampp/htdocs on the computer (not case-sensitive). If it is not found, exit with the warning that either MAMP or XAMPP should be installed.
Download the latest distribution files from GitHub: https://github.com/bolprocessor/bolprocessor/archive/graphics-for-BP3.zip https://github.com/bolprocessor/php-frontend/archive/master.zip https://github.com/bolprocessor/bp3-ctests/archive/main.zip
Unzip these three files. They create folders with names: bolprocessor-graphics-for-BP3 php-frontend-master bp3-ctests-main
Create a folder named "bolprocessor" (if it does not yet exist) inside the "htdocs" folder of the Apache server
Copy bolprocessor-graphics-for-BP3/source to htdocs/bolprocessor/ If there is already a "source" folder, delete it
Copy bolprocessor-graphics-for-BP3/Makefile to htdocs/bolprocessor/ Copy bolprocessor-graphics-for-BP3/BP3_help.txt to htdocs/bolprocessor/ Copy bolprocessor-graphics-for-BP3/Credits.txt to htdocs/bolprocessor/ Copy bolprocessor-graphics-for-BP3/BP3-To-Do.txt to htdocs/bolprocessor/ Copy bolprocessor-graphics-for-BP3/License.txt to htdocs/bolprocessor/ Copy bolprocessor-graphics-for-BP3/ReadMe.txt to htdocs/bolprocessor/
Copy bolprocessor/php/_settings.php to bolprocessor/ (if it exists)
Copy php-frontend-master/php to htdocs/bolprocessor/ If there is already a "php" folder, delete it
Copy bolprocessor/_settings.php to bolprocessor/php/ (if it exists)
Create a folder htdocs/bolprocessor/csound_resources if it does not yet exist
Copy the content of php-frontend-master/csound_resources to htdocs/bolprocessor/csound_resources Files that already exist should be replaced with their updated versions
Create a folder htdocs/bolprocessor/ctests if it does not yet exist
Copy the content of bp3-ctests-main to htdocs/bolprocessor/ctests Files that already exist should be replaced with their updated versions
Delete the temporary download directory
Set permissions of the bolprocessor folder recursively to "775"
➡ There is no security risk in setting "775" permissions, as the MAMP or XAMPP Apache server will be running on your private computer. The Bol Processor never creates/modifies files outside of its "bolprocessor" folder.
Delete htdocs/bolprocessor/bp if it exists. This ensures that the 'bp' console is recompiled after each update.
Uninstall the Bol Processor
Uninstalling the Bol Processor, and all the data downloaded or created for its use, is very simple: delete the "htdocs/bolprocessor" folder.
