A GitHub repository is comprised of folders containing files such as the all-important source code files. Usually, there are many other types of files in the repository. There might be documentation files, man pages, software license files, build instructions and shell script files. There are no rules regarding what a repository should or must contain, but there are conventions.
README
It's traditional to include a readme file in a repository. It might be called readme, Readme, or README. It might have an extension of ".md" or no extension at all.
GitHub automatically puts the contents of the readme file on the front page of the repository. If the readme file has a ".md" extension, it will contain Markdown markup language. This allows the developers to use style elements, such as fonts, bullet points, and images.
Typically, a readme file has sections that tell you what the project is about, what the type license is, who maintains the project, how to get involved, and how to build and run the application.
The boxes Repository
Our mission is to clone the boxes repository, and then build the boxes application.
The repository follows the same layout the Atom one did. There's a list of folders and files and below that is the contents of the readme file. It follows the standard layout for a repository, but it's a smaller project, so there are fewer folders and files.
The readme file is briefer too. It has a section called "Development." In that section is a link entitled "building from source." If we follow that link, we should find the information we need.
There's usually some lightweight sleuthing necessary to navigate the repository and find the information you want, but it's not difficult. Read everything on the repository page carefully. Sometimes, the information is there but might not be prominently displayed.
Dependencies
The "Building from Source" page has a section called "Building on Linux," and that's just what we need. It says we must have a C compiler, Bison, and Flex installed.
Tool Set
Ubuntu had to have Git, Flex, Bison, and make installed. Here are the commands:
sudo apt-get install git
sudo apt-get install flex
sudo apt-get install bison
sudo apt-get install make
Cloning the Repository
Each GitHub repository has a specific web address used with Git to clone the repository to your computer. On the main page of the boxes repository, there's a green button labeled "Clone or download."
Click the button to see the web address. This is the address we must pass to the git command when we clone the repository.
Change into the directory that we want to have the repository cloned into, and then use this command. If your terminal window supports it, you can copy and paste the web address into the command. Press Ctrl+Shift+V to paste into a GNOME terminal window.
Git clones the remote repository and creates a local one on your computer. It tells us it's cloning into a directory called "boxes."
The boxes directory is created within the directory from which you issued the git command. If we switch to the boxes directory and look at the contents, we see the same list of files and folders we saw on the GitHub page.
Great! We've successfully cloned the source code and other files to our computer. Now, we need to build the application.
Building the Application
To build the application, we must follow the instructions on the GitHub repository. Sometimes, we'll run a particular shell file, and others we'll run make. The build instructions we're following told us to run make.
The make utility reads and performs a set of instructions from a makefile. These instructions tell make how to compile the program and link it together. make passes the instructions to the compiler and other build tools.
The command we're told to use will call make twice. The first call to make builds the application, and the second runs a suite of tests.
The command the build instructions told us to use is:
make && make test
Deploying the boxes Application
he application has been built, and we have an executable binary. We must now copy the binary to the /usr/bin/ directory. This allows the shell to find it when we try to use it.
For some applications, this might be all you have to do. In other cases, you might need to copy additional files, such as man pages and config files, into locations in the filesystem. The latter is what we have to do with our new application because it was in the build instructions.
Use sudo to run these commands. The first command copies a man page into the man1 directory:sudo cp doc/boxes.1 /usr/share/man/man1
Next, copy the global config file to a directory in /usr/share/:sudo cp boxes-config /usr/share/boxes
Finally, copy the binary to /usr/bin:sudo cp src/boxes /usr/bin
Testing the boxes Application
man boxes
echo How-To Geek | boxes
echo How-To Geek | boxes -d whirlyecho How-To Geek | boxes -d c-cmt2
boxes -l | less
Build Complete
The steps to build from source are usually straightforward:
Review the build instructions on the repository.
Check you have the required tools installed and install any that are missing.
Clone the repository to your computer.
Follow the build instructions, which are often as simple as typing make.
Copy the file(s) to the required locations.
If there are steps in the build instructions that are unclear, see if the project has a forum or community you can send a question to. If the application has a website, they might have a "Contact Us" page. The developer who maintains the boxes project has his email on the "About" page of the boxes website. That's a generous gesture on his part, and typical of the wider open source community.
