MyroC Installation and Comments for Linux Materials to Support a C-based Course with Scribbler 2 Robots

Installing MyroC.3.33.3b

This page organizes instructions and notes for the installation of version 3.33.3b of the MyroC package on Linux.

Notes:

• Instructions on this page reflect careful testing and review on laptops through Spring 2021.
• These instructions utilize the apt command-line utility for installing and maintaining packages, and this tool greatly simplifies the installation of several packages needed to support MyroC. In practice, apt is typically included in on Ubuntu, Debian, and related Linux distributions.
• MyroC.3.3 reflects updates to display images on Linux/Debian, but the instructions that follow may require some adjustments for new Linux versions.

General Comments

This section includes for general background—before one starts the actual installation process. Overall, these notes fall into three categories: needed directories, permissions with the sudo command, and the use of the apt package manager.

Needed Directories

Installation of MyroC and related packages typically involves two directories, and a user has considerable latitude regarding which directories to use in this process.

• A working directory: A directory is needed for downloading materials, decompressing, compiling, and similar processing. For simplicity, the installer might consider creating a "MyroCPackage" directory (perhaps within a user's home directory) for this work.
• A reference directory: A main directory is needed for the final include files, shared library objects, and a few scripts and compiled programs. Again, for simplicity, the installer might consider creating a "MyroC" directory (again within a user's home directory) for this system-wide reference.

Conceptually, the reference directory, mentioned above, might reasonably be designated as /usr or /usr/local or /usr/local/share.

• If a system administrator performs the installation, this might be a reasonable choice.
• However, if the installer is a regular user, some files will have to be placed in the installer's directory and some in the reference directory. In practice, these directories likely have different owners, so that installation will involve a combination of make and sudo make directives. (sudo is explain further in the next general comment.)

  In my experience, working between these two worlds is challenging, as the owner of one directory is not the same as the owner of the other. For this reason, it is suggested that the reference directory (e.g., MyroC) be placed within the installer's directory structure. In this setting, all files can be compiled and installed with a consistent owner, and system references to these files can be accomplished in a reasonable way using sudo

Permissions with the sudo command

In what follows, all commands are assumed to be executed in a terminal window.

During installation, several steps utilize the sudo command, run in a terminal window. The sudo command allows a user to run certain, authorized commands (e.g., system commands) without having general administrative privileges.

• Example: One step in the installation of the eSpeak speech synthesizer requires a copy of the speak program to be placed in the /usr/local/bin directory. Once the speak program has been downloaded, a natural command might be

  cp speak /usr/local/bin
  

• Permissions: Since the /usr/local/bin directory is owned by the system administrator for the computer (sometimes called "root"), a normal user cannot make changes in this directory. Thus, the user would type

  sudo cp speak /usr/local/bin
  

• Using sudo: With this sudo command, the system will ask for your password for authentication. If you type your password correctly, and if you are authorized for this command, then the system will perform the desired work, and the speak program will be copied as you wished.

The apt Package Manager

As noted above, this guide relies on the usage of the apt package manager for the installation of some programs.

• Using apt: For the unacquainted, a package manager is a tool that allows you to easily install, update, and remove software. But don't worry if you haven't heard of a package manager before - your distribution already comes with one installed! If you are using Debian, Ubuntu, or Linux Mint, your system comes with the 'apt' package manager: the default for this guide. All you need to do is copy and paste the commands in the instructions. We'll also explain what we're doing in each command so you'll learn more about 'apt' itself.
• History: In the early days of computing, users installed packages from "source": meaning that they had to download the original source code and compile it themselves. This was cumbersome in several ways: compilation itself could be time-consuming, there was no guarantee that your compiler and computer would successfully compile a program written on another system, program dependencies were sometimes difficult to manage, and updating programs was complicated.
  • The make facility could simplify the process somewhat, but challenges arose with some frequency.
  • As an example, the first version of MyroC (in 2011) was built upon a MyroC++ library, which in turn drew upon numerous packages. Installation utilized a make/Makefile process, but the installation on some machines could take 4 hours—and if something went wrong in the process, finding the trouble could require substantial work.
• Package managers usually solve these issues by distributing executables instead of the original source code – so there's no compilation required. They also track dependencies – so they can automatically install your program's prerequisites.

Preliminaries

The installation instructions that follow assume that various standard Linux packages have already been installed. The system administrator of one Linux system has remarked that the following packages should be installed before further work proceeds.

• libbluetooth

• libbluetooth-dev

External Packages

MyroC depends upon several third-party packages:

• eSpeak
• PulseAudio
• ligjpeg
• OpenGL

Fortunately, each of these packages can be installed easily using the apt package manager.

1. Type the following line in a terminal window so that the apt package manager has up-to-date information on what is already installed on your machine.

     sudo apt update
       

2. Install the needed packages by entering the following line in a terminal window.

     sudo apt install libbluetooth3 libbluetooth-dev libxmu-dev libxmu-headers libxi-dev libpulse-dev libespeak-dev libjpeg-dev libopengl-dev
         

   Note: If you enjoy typing long lines, then you are free to type this yourself in a terminal window. For others, a copy-and-paste of this line would work nicely.

eSpeakPackage

As noted in the General Comments near the top of this page, the following procedures assume the user has established a base directory for the downloading and installation of the eSpeak and MyroC packages. For example, the user might create a base directory, perhaps called "MyroCPackage".

1. In a terminal window, move to the created base directory, with a command such as:

   cd                  # since earlier commands reference various directories, go home first
   cd MyroCPackage  # base directory for MyroC installation
   

2. Download the compressed archive file, MyroC.3.33.3b.tgz to your created base directory

   • If the computer places the file in your Downloads directory, use the browser's Download icon to locate and move the file to your created base directory.

3. Although the original file, MyroC.3.33.3b.tgz, is a compressed archive file, the Linux environment may or may not decompress the file automatically during download.

   • If the downloaded file appears with a .tgz extension, then decompress the file and expand the archive with the command:

     tar -xzvf MyroC.3.33.3b.tgz

   • If the downloaded file appears with a .tar extension, then file has already been decompressed. Expand the .tar file with the command:

     tar -xvf MyroC.3.33.3b.tar

Following this extraction, the following files and directories should be found in a new MyroC.3.33.3b subdirectory.

• README.txt: a file with a high-level overview of the MyroC package
• License.txt: a summary of the Creative Commons Attribution-Noncommercial-Share Alike 4.0 International License under which all MyroC software is distributed.
• eSpeak: a directory of implementation-related files for the eSpeak package, version 3.0
• eSpeak-documentation: a directory containing documentation for the eSpeak package, in html format
• MyroC.3.3a: a directory of implementation-related files for the MyroC package, version 3.3a
• MyroC-documentation: documentation for the MyroC package, in both html and latex formats
• test-programs: several C programs to aid testing of the MyroC program

All materials for the eSpeakPackage are (not surprisingly) located in the eSpeak directory.

4. Move from the general MyroCPackage directory to its eSpeak subdirectory.:

   cd eSpeak
     

The internal algorithms and code for the eSpeakPackage are quite different on Linux, Mac OS X, and Windows 10. Thus, the downloading and decompression process for the MyroCPackage creates four subdirectories for the eSpeakPackage:

• eSpeakPackage-linux.3.0: a directory containing the C-based infrastructure that allows the use of the eSpeak speech synthesizer within a Linux framework, together with several test programs
• eSpeakPackage-mac.3.0: a directory for use in a Macintosh environment, containing the C-based infrastructure that allows the use of the eSpeak speech synthesizer, together with several test programs
• eSpeakPackage-windows.3.0: a directory for use in a Windows 10 environment, containing the C-based infrastructure that allows the use of the eSpeak speech synthesizer, together with several test programs
• eSpeakTest.c, eSpeakExample1.c, eSpeakExample2.c: applications for use in testing the eSpeakPackage and its installation.
  (Note: eSpeakTest.c and eSpeakExample1.c test the eSpeakPackage directly. eSpeakExample2.c requires the installation of both the eSpeakPackage and MyroC.)

On Linux, the natural approach is to use the eSpeak API to utilize various functions directly within a C program. The eSpeakPackage using this API is collected in subdirectory:

• eSpeakPackage-linux.3.0

4. To install the eSpeakPackage for Linux, move to the eSpeakPackage-linux.3.0 directory.

         cd
         cd MyroCPackage
         cd eSpeak
         cd eSpeakPackage-linux.3.0    

   The listing includes the following files:

   • eSpeakPackage.h: the header file for C programs calling the functions for eSpeak
   • eSpeakPackage.c: the eSpeakPackage implementation file
   • eSpeakIntro.html: Web-based documentation for using the eSpeakPackage
   • textlines-to-speech.c: a program interface between the eSpeechPackage and the external eSpeak code by Jonathan Duddington.
   • eSpeakTest.c, eSpeakExample1.c, eSpeakExample2.c: applications for use in testing the eSpeakPackage and its installation.
     (Note: eSpeakTest.c and eSpeakExmaple1.c test the eSpeakPackage directly. eSpeakExample2.c requires the installation of both the eSpeakPackage and MyroC.)
   • Makefile-linux-implementation: a file, used with the make utility, to compile and install the eSpeakPackage

    rm Makefile
    ln -s Makefile-mac Makefile
  

Installation Options for the eSpeakPackge on Linux

Installation of the eSpeakPackge requires primary decisions.

• Determining where needed programs and libraries should be placed.
• Considering whether the computer(s) will have accounts that allow different users to log in remotely.

Determining Directories

Within Linux, it is common for programs installed by the user to be placed in subdirectories or /usr/local. In particular,

• /usr/local/include is a commonly-used directory of header files.
• /usr/local/bin is a commonly-used directory for locally-installed programs.
• /usr/local/lib is a commonly-used directory for code libraries.

6. Check the beginning of the file Makefile-linux-implementation, so that the base directory for this installation is correct.

   • If eSpeakPackage files should be installed in /usr/local/ and its subdirectories, then Makefile-linux-implementation likely may be used without change.
   • If eSpeakPackage should be installed elsewhere, then edit the first few line(s) of Makefile-linux-implementation to reflect the desired directories.

Installation on a Private Computer versus a Computer with Multiple User Accounts

Typically, a personal laptop is owned by one person, and that person is the only one who can log onto the machine. However, for machines in labs or machines on which several people have accounts, one person could be using the machine while another logs in remotely. In this context, an awkward situation could arise if the remote user logged in to the computer and used the eSpeakPackage to "talk" to a logged in user.

7. Due to these two environments, the eSpeakPackage has two compilation/installation options.

   • If remote users can log into a computer, but they should not be allowed to utilize the eSpeakPackage remotely, then the eSpeakPackage can be compiled and installed with the command:

               make computer=shared install/espeak
             

   • If a personal computer will not be bothered by remote logins, the the following command can be used for compilation and installation.

               make install/espeak
             

   If the above command produces a permissions error, use sudo with the above command:

         sudo make computer=shared install/espeak
       

   or

         sudo make install/espeak
       

8. The above instructions likely handle software installation. However, workstations often are set up with their audio muted. If running test programs yields long pauses when printed output appears, but no sound, check the audio settings.

   • Check the audio is not muted.
   • Set the volume level that is audible, but not overwhelming.

• In many environments, this approach works fine on some Linux installations (e.g., the Debian installation on MathLAN at Grinnell College).
• However, on some other Linux installations , (e.g., the Ubuntu installation on the Linux network at The University of the South), some functions within this APE do not seem to work properly.. In this case, an alternative approach utilizes the binary program espeak, in binary form at eXpeakPackate-linux-alt.tar.

Testing the eSpeak and eSpeakPackage download and installation

• After compiling the eSpeakPackage (step 5), both programs eSpeakTest.c and eSpeakExample1.c can be compiled and run:

  make eSpeakTest
  ./eSpeakTest
  make eSpeakExample1
  ./eSpeakExample1
  

• Note that eSpeakExample2.c will not compile correctly until the MyroC package already is installed; other programs should compile without trouble.

As noted above, if the installation in

eSpeakPackage-linux.3.0

does not seem to work, try a similar process with the alternative implementation in

eSpeakPackage-linux.3.0-alt

MyroC.3.33.3b

Installation of the eSpeakPackage required downloading and decompressing the archive file MyroC.3.33.3b.tgz. From the created base directory (e.g., "MyroC"), move to the MyroC.3.3 release subdirectory, and then its subrelease MyroC.3.33.3b subdirectory:

1. Move to the MyroC.3.33.3b subdirectory:

   cd            # since earlier commands reference various directories, go home first
   cd MyroC      # base directory for MyroC installation
   cd MyroC.3.3  # the release subdirectory
   cd MyroC.3.33.3b # the subrelease subdirectory
   

    rm Makefile
    ln -s Makefile-linux Makefile
  

3. The beginning of file Makefile-linux contains an INSTALLPATH variable that designates where the MyroC material should be placed. Pragmatically, this location depends upon the system involved.

   • On MathLAN, this is usually a private account, such as /home/walker/MyroC
   • On a private computer, this is usually /usr/local

   Edit Makefile-linux as needed to designate the desired directory for this installaton.

4. Compile and install the MyroC package in system directories:

   make install/MyroC
   

5. As with the eSpeakPackage installation, report the relevant files to the Linux operating system (see Step 9 in the eSpeakPackage installation above).

Testing and Running MyroC Programs

Several test programs are available in the test-programs subdirectory of the base directory.

Preliminary Step: Using MyroC with Scribbler 2 robots requires setting up Bluetooth so the workstation/laptop and robot(s) are properly paired. See Bluetooth Setup for Linux Workstations/Laptops for details — before trying to run test programs.

Compiling MyroC programs requires use of numerous compilation flags, compiling normally uses a Makefile. As with installation, compilation flags must be tailored to the Linux environment.

Unfortunately, the specific libraries required for graphics and infrastructure vary substantially from one Linux environment to another. For this reason, this MyroC.3.3a package contains two distinct Makefiles for compiling application programs.

• Makefile-linux-mathlan: flags required for libraries on the MathLAN networked lab.
• Makefile-linux-pc: flags required for libraries installed by the apt Package Manager.

Whatever flags are needed, compiling is based on files in the test-programs subdirectory of MyroC.3.3.

1. Move to the MyroC.3.3 directory that you created earlier (not MyroC.3.33.3b), and then move to its test-programs subdirectory.

2. From the MyroC.3.3 directory, move to the test-programs subdirectory.

   cd test-programs
   

3. In the test-programs subdirectory, designate the proper Makefile version as the relevant framework for compiling MyroC programs.

   • If working on MathLAN, the relevant Makefile version is Makefile-linux-mathlan. Use the following command to make use of this version:

     ln -s Makefile-linux-mathlan Makefile
         

   • If working on a computer for which the apt Package Manager has installed relevant infrastructure, the appropriate Makefile version is Makefile-linux-pc. Use the following command to make use of this version:

     ln -s Makefile-linux-pc Makefile
         

   If neither of these Makefile versions work in the following steps, you will need to determine what libraries contain the relevant functions (see the program header files) as well as the locations of the directories that contain those libraries.

4. Test programs can be compiled with a simple make command. For example, running the spirit-song.c program utilizes these steps:

   make spirit-song
   ./spirit-song
   

   Note: If this step generates errors that rBeep and other MyroC functions are "Undefined symbols" or that there is a "clang: error", double check that the "ln -s" command above has been issued, and a new file (called Makefile) is present in the same directory as your program. See also the notes after Step 4 below.

5. To compile programs in any other user directory (except eSpeak and MyroC.3.33.3b), copy the appropriate Makefile-linux version file to the user directory — using the name Makefile.

   Notes: Compiling and installing both the eSpeakPackage and MyroC require different commands from compiling and running user programs (once these packages have been installed). Thus, the Makefile-linux files in the eSpeak and MyroC subdirectories are different from the Makefile-linux file in the test-programs subdirectory. Be sure to utilize the Makefile-linux in the test-programs subdirectory as the appropriate Makefile for user programs utilizing either the eSpeakPackage or MyroC.

created 17 October 2015 revised 19 October 2015, revised 23 February 2016 revised for alternate Linux environments 22 January 2017, 26 February 2021
For more information, please contact Henry M. Walker at walker@cs.grinnell.edu.