Tag: MacOS

   

This is a sup­ple­ment to the page Bol Processor ‘BP3’ and its PHP inter­face.

A one-click nota­rized installer of Bol Processor BP3 is avail­able. It is called "BolProcessorInstaller.pkg" and it can be down­loaded from here (unique location).

Geeks may pre­fer an equiv­a­lent method using a script includ­ed in this pack­age, see below.

This installer (or the script) is used for both ini­tial instal­la­tion and updates. Each time you run it, it will down­load the lat­est ver­sions of the BP3 con­sole source files, the inter­face PHP files and the sam­ple set con­tained in the 'ctests' fold­er. Data, gram­mars and scripts that you've cre­at­ed will not be delet­ed. However, if you have mod­i­fied files in the 'ctests' fold­er, they will be revert­ed to the cur­rent dis­tri­b­u­tion version.

Install MAMP or XAMPP

If you try to run the installer of Bol Processor, it will first check that a local Apache serv­er (either MAMP or XAMPP) has been installed. Both are suit­able since the Bol Processor inter­face con­tains exclu­sive­ly HTML, PHP and JavaScript code. No data­base is required.

As of January 2025, it appears that the free ver­sion of MAMP has a script exe­cu­tion time of 30 sec­onds that can­not be over­rid­den by the PHP scripts. If this lim­i­ta­tion is con­firmed, we will rec­om­mend the use of XAMPP (free) or MAMP PRO (for a charge).

Your Mac may refuse to run the XAMPP installer because it is from an "unknown devel­op­er". You can over­ride this by allow­ing the appli­ca­tion in the Privacy & Security sec­tion of the Mac's System Settings. Unpacking the files takes sev­er­al min­utes, so be patient and wait for it to finish!

👉 Don't try the vir­tu­al machine ver­sion of XAMPP! It won't work on Macs with M1 chips (and above). Use the native installer.

if you choose the (free) MAMP ver­sion, both MAMP and (com­mer­cial) MAMP PRO will be installed. The inter­face will occa­sion­al­ly prompt you to "upgrade" to MAMP PRO (see pic­ture), although you don't need it for the Bol Processor!

Note that after down­load­ing MAMP, you will find MAMP PRO in the Applications fold­er, where­as MAMP (free) is locat­ed in Applications/MAMP. Also note that this ver­sion of MAMP runs on port "8888" by default, as we will see below.

For MAMP, the "htdocs" fold­er is in Applications/MAMP. For XAMPP, it is in Applications/XAMPP/xamppfiles. The installer will find it in both cases.

👉  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…

Start Apache at boot time

If you want Apache to start auto­mat­i­cal­ly when you start your com­put­er, this process is easy with MAMP: check Login items in the sys­tem settings.

For XAMPP, things are a bit more complicated.

For geeks: You have the offer to cre­ate a start­up script but is not entire­ly sat­is­fac­to­ry with the cur­rent ver­sion (8.2.4). It allows XAMPP to restart Apache at boot time and PHP pages are dis­played cor­rect­ly. However, when real-time MIDI is used, MIDIClientCreate() returns an error.

Until this prob­lem is fixed, the eas­i­est way is to find the Application Manager manager-osx.app (in XAMPP/xamppfiles) and add it to the Login Items of the General set­tings of your MacOS system:

You can also place an alias of "manager-osx.app" on the desk­top and click on it at start­up if you intend to run the Bol Processor.

MAMP PRO

Below are instruc­tions for rich peo­ple run­ning MAMP PRO.

1. Launch MAMP PRO from the Applications folder.
2. In the MAMP main win­dow, click the Apache Enable but­ton (see image). No need for MySQL.
3. The image shows the default set­tings for PHP, which is start­ed with Apache.
4. In case of trou­ble, check the set­tings for ports (see image) and of hosts (gen­er­al  and  Apache).

XAMPP

Open the XAMPP fold­er in the  Applications  fold­er and launch  manager-osx.app  as shown below.

The XAMPP main page will appear. If you click on the  Manage Servers  tab and select  Apache Web Server, then Configure, you can make sure that the serv­er is run­ning on port "80". This can be changed (e.g. to "81") if it cre­ates a conflict.

Then click the Start but­ton. If there is no con­flict with the ports, Apache will show up as "run­ning":

Once Apache is run­ning, you can click on the  Welcome  tag and the  Go to Application  but­ton. This should dis­play a (local) page about XAMPP in the path  http://localhost/dashboard. Both the  dashboard  and (lat­er)  bolprocessor  fold­ers will be locat­ed in the  Applications/XAMPP/xamppfiles/htdocs  folder.

Install the Bol Processor

After installing XAMPP or MAMP, you can run the installer "BolProcessorInstaller.pkg" or the "install_bolprocessor.sh" script. Both are equivalent.

By default, all Bol Processor pro­gram, doc­u­men­ta­tion and data files will be cre­at­ed in a fold­er called "bolprocessor" and will be con­tained in the "htdocs" fold­er cre­at­ed by XAMPP or MAMP — in oth­er words, on your start­up disk. This is not a prob­lem as the whole set does not take up much space, typ­i­cal­ly less than 60 Mb when installed, and the Bol Processor data is basi­cal­ly pure text.

However, you may wish to install the "bolprocessor" fold­er to a dif­fer­ent loca­tion, includ­ing an exter­nal device. In this case, fol­low the instruc­tions for Relocating "bol­proces­sor" before run­ning the installer or the script.

Using the installer

Download "BolProcessorInstaller.pkg" from here and double-click it.

👉  If you have pre­vi­ous­ly down­loaded an old­er ver­sion of the installer, your brows­er may be deliv­er­ing the old ver­sion instead of the lat­est. The safest thing to do is to check the size of "BolProcessorInstaller.pkg" (reed below the Security sec­tion). If nec­es­sary, use a dif­fer­ent brows­er for the download.

This installer has been nota­rized, which means it con­tains infor­ma­tion that allows Apple to cer­ti­fy its valid­i­ty. The only changes you will have to con­firm are stan­dard soft­ware instal­la­tion changes on your Mac.

For geeks: The installer sets up user/group para­me­ters in the "bolprocessor" fold­er: "daemon:admin" if XAMPP is the Apache serv­er. If MAMP is used, the "<user_id>:admin" set­ting is retained.

Once that's done, go down to the sec­tion Compile the 'bp' con­sole.

Using the script (geeks only!)

An equiv­a­lent method is to run the "install_bolprocessor.sh" script found in the "macos-scripts" fold­er down­loaded here. This makes it pos­si­ble to under­stand each step of the instal­la­tion and pos­si­bly sug­gest improvements.

After down­load­ing "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" fold­er cre­at­ed by XAMPP or MAMP, it will stop the instal­la­tion, warn­ing you that one of them should be installed.

👉 The installer will cre­ate a "bolprocessor" fold­er in the "htdocs" fold­er used by XAMPP (first choice) or MAMP (sec­ond choice). If you have used XAMPP in the past and want to switch to MAMP, you will need to rename the "XAMPP" or "xamppfiles" fold­er before run­ning the installer.

Compile the 'bp' console

There is a Go to Application but­ton on XAMPP man­ag­er and a WebStart but­ton on MAMP (free) which will dis­play a page con­firm­ing that the Apache serv­er is running.

Now, assum­ing that the instal­la­tion was suc­cess­ful, and the Apache serv­er is run­ning, start XAMPP or MAMP and point your brows­er to  localhost/bolprocessor/php/ or (if it doesn't work) to localhost:8888/bolprocessor/php/.

One of these will dis­play the home page of the Bol Processor. The default port used by the free MAMP is "8888", but you can change it to "80" in MAMP set­tings (see pic­ture), so that the ":8888" option is no longer required.

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 com­pile the con­sole, which will take a minute or two.

👉  It is very unlike­ly that the com­pi­la­tion will fail. If it ever hap­pens, please con­tact us!

If you don't see the link to com­pile, and instead a men­tion that 'gcc' is not respond­ing, you may need to install the Xcode toolk­it on your machine (link to App Store).

Install and launch Xcode (free) to enable the com­pi­la­tion. Click "Cancel" when Xcode asks you to "cre­ate a project", go back to the Bol Processor page and reload it.

Now, you will see the com­pi­la­tion link.

👉  There are oth­er meth­ods of installing 'gcc'. Fans of Terminal com­mands can sim­ply try the command:

brew install gcc

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 dif­fer­ent approach to sound synthesis.

Just down­load a pre-built instal­la­tion of Csound (MacOS 6.18) from its down­load page.

The BP3 inter­face should be able to fig­ure out the loca­tion of "csound" and fix its path accord­ing­ly. If it does not respond, you will be asked to change the path and per­haps the name of the Csound con­sole (see image).

😀  Now, the Bol Processor is ful­ly oper­a­tional! You can try exam­ples con­tained in the 'ctests' fold­er, or fol­low the guid­ed tour on page Bol Processor ‘BP3’ and its PHP inter­face.

Updating to new versions

To update the Bol Processor con­sole, its PHP inter­face and exam­ples (the con­tents of the "ctests" fold­er), sim­ply rerun "BolProcessorInstaller.pkg". Using the lat­est ver­sion is safe!

The installer will down­load and install cur­rent ver­sions of the soft­ware and data. It will delete the com­piled  "bp"  con­sole and prompt you to recom­pile it (with a sin­gle click).

Updating will not mod­i­fy or delete any data you have cre­at­ed in the "ctests" fold­er or out­side it. However, if you have mod­i­fied a sam­ple file with­out chang­ing its name, it will be revert­ed to its dis­tri­b­u­tion version.

The installer will also pre­serve the "_settings.php" file (if it exists), which con­tains your project settings.

Security

You are right to be con­cerned about secu­ri­ty. Can you be sure that you have down­loaded the cor­rect (and lat­est) ver­sion of "BolProcessorInstaller.pkg"? Normally yes, this installer is safe because it has been nota­rized.

The size of the "BolProcessorInstaller.pkg" file is exact­ly 18987 bytes and its MD5 is
9be05c728209f3b49de9a15287351901. 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: 6 January 2025.

Please DO NOT SHARE THE INSTALLER, only its link: https://bolprocessor.org/misc/BolProcessorInstaller.pkg

Geeks may want to cus­tomise it for their own use. Just down­load this fold­er which con­tains the script files (install_bolprocessor.sh and postinstall) along with instruc­tions on how the installer has been built.

For read­ers not con­ver­sant with Unix shell scripts, the fol­low­ing is a descrip­tion of the process in human language:

Check that an Apache serv­er MAMP or XAMPP is installed by find­ing either MAMP/htdocs or xampp/htdocs on the com­put­er (not case-sensitive). If it is not found, exit with the warn­ing that either MAMP or XAMPP should be installed.

Download the lat­est dis­tri­b­u­tion 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 cre­ate fold­ers with names:
bolprocessor-graphics-for-BP3
php-frontend-master
bp3-ctests-main

Create a fold­er named "bol­proces­sor" (if it does not yet exist) inside the "htdocs" fold­er of the Apache server

Copy bolprocessor-graphics-for-BP3/source to bolprocessor/
If there is already a "source" fold­er, delete it

Copy bolprocessor-graphics-for-BP3/Makefile to bolprocessor/
Copy bolprocessor-graphics-for-BP3/BP3_help.txt to bolprocessor/
Copy bolprocessor-graphics-for-BP3/Credits.txt to bolprocessor/
Copy bolprocessor-graphics-for-BP3/BP3-To-Do.txt to bolprocessor/
Copy bolprocessor-graphics-for-BP3/License.txt to bolprocessor/
Copy bolprocessor-graphics-for-BP3/ReadMe.txt to bolprocessor/

Copy bolprocessor/php/_settings.php to bolprocessor/ (if it exists)

Copy php-frontend-master/php to bolprocessor/
If there is already a "php" fold­er, delete it

Copy bolprocessor/_settings.php to bolprocessor/php/ (if it exists)

Create a fold­er bolprocessor/csound_resources if it does not yet exist

Copy the con­tent of php-frontend-master/csound_resources to bolprocessor/csound_resources
Files that already exist should be replaced with their updat­ed versions

Create a fold­er htdocs/bolprocessor/ctests if it does not yet exist

Copy the con­tent of bp3-ctests-main to bolprocessor/ctests
Files that already exist should be replaced with their updat­ed versions

Delete the tem­po­rary down­load directory

Set per­mis­sions of the bol­proces­sor fold­er recur­sive­ly to "775"

➡ There is no secu­ri­ty risk in set­ting "775" per­mis­sions, as the MAMP or XAMPP Apache serv­er will be run­ning on your pri­vate com­put­er. The Bol Processor nev­er creates/modifies files out­side of its  "bolprocessor"  folder.

Delete bolprocessor/bp if it exists. This ensures that the 'bp' con­sole is recom­piled after each update.

Relocating "bolprocessor"

The Bol Processor can be installed out­side the "htdocs" fold­er cre­at­ed by MAMP or XAMPP (on your boot dri­ve). You might want it near relat­ed projects, or use extra space from an exter­nal hard dri­ve. There may also be sit­u­a­tions where cre­at­ing files on the boot dri­ve is restrict­ed to the super admin.

Fortunately, the process of relo­cat­ing is very simple.

If you have already cre­at­ed a "bolprocessor" fold­er by run­ning the installer, drag it to the desired loca­tion and delete it from the "htdocs" fold­er. If not, cre­ate an emp­ty "bolprocessor" fold­er in the desired location.

Then, open the Terminal (in the Applications fold­er) and point it to the "htdocs" direc­to­ry. For those unfa­mil­iar with Unix com­mands, you will need to type "cd " (fol­lowed by a space) and drag "htdocs" to the end of this com­mand, then press "return". You can type the instruc­tion "ls -al" to see the con­tents of "htdocs", which is nor­mal­ly empty.

Let's say you've cre­at­ed an emp­ty fold­er "bolprocessor" inside a fold­er called "MUSIC" on an exter­nal dri­ve called "EXT". The instruc­tion cre­at­ing the sym­bol­ic link is:

ln -s /Volumes/EXT/MUSIC/bolprocessor bolprocessor

Make sure that the sym­bol­ic link you cre­at­ed points to the cor­rect loca­tion: you will now see a "bolprocessor" icon with a small arrow in the bot­tom left cor­ner. Double-click it, it should open the des­ti­na­tion folder.

👉 You may won­der why sym­bol­ic links are used instead of MacOS alias­es, which do not require the use of the Terminal. The rea­son is that the Apache servers don't accept alias redirections.

You can now safe­ly run the installer (or install script) and pro­ceed to com­pile the 'bp' con­sole. Make sure you use the lat­est ver­sion of the installer (from 3 January 2025), as it is designed to work with sym­bol­ic links.

👉 Never change the names of the "bolprocessor" fold­er and sym­bol­ic link, oth­er­wise the instal­la­tion will fail.

The first time you run the Bol Processor, MAMP or XAMPP may ask your per­mis­sion to dis­play files out­side its "htdocs" fold­er. Please con­tact us if you're expe­ri­enc­ing issues with this relocation!

If you're not afraid of sym­bol­ic links, you can use the same tech­nique to relo­cate some data files out­side the "bolprocessor" fold­er, for exam­ple to a loca­tion shared by Dropbox.

Uninstall the Bol Processor

Uninstalling the Bol Processor, and all the data down­loaded or cre­at­ed for its use, is very sim­ple: delete the "bolprocessor" fold­er, and the "bolprocessor" sym­bol­ic link if you have cre­at­ed it.

Bernard Bel
Creation: August 2024