Have you been told to “clone the repo and build it,” and don’t know what to do next? We’ll show you how to get that program on GitHub running on Linux, even if you’re a beginner.
The instructions that make up a computer program are written, edited, and saved in text files. A program called a compiler then processes these files. This produces the executable version of the program. The text files of instructions are called the source code. The version of the program that can actually run on a computer is called the binary or the executable.
That’s a simplified version of events, but it paints a correct—if generalized—picture. In practice, you’ll find all sorts of variations on that model. Sometimes, other programs generate the text files. Other times, the source code runs inside an interpreter and doesn’t need to be compiled, and so on.
However, the one universal truth across all software projects is this: the source code files are the crown jewels, and they need to be looked after just as carefully.
Version Control Programs
All of the source code files within a project are called the codebase. Large projects often have many developers working on the codebase. Every code change must be tracked and identifiable. If required, the changes must be reversible. If different developers make changes to the same source code file, their edits must be merged.
It’s not surprising, then, that software programs called version control systems exist to make the management of changes to the codebase easier. Version control systems hold all previous versions of each file in the codebase, and every change is recorded, commented on, and tracked.
A Little Thing Called Git
Linus Torvalds, the creator of the Linux kernel, developed a version control program called Git to administer the Linux kernel codebase. It’s now the world’s most widely adopted version control software. There are millions of people using it—literally.
With Git, a project’s codebase is stored in repositories. In addition to the local repositories that sit on developer’s computers and, perhaps, on a central server on the network, it’s a good practice to have an off-site, or remote, repository.
And that’s where GitHub comes in.
GitHub was created as a result of
git‘s success. The founders saw the emerging need for securely hosted remote
git repositories. They launched a business providing a cloud platform to allow development teams to host remote repositories. As of April 2019, GitHub hosts over 100 million repositories.
If an application is an open-source project, the chances are very high that it will be hosted on GitHub. There are other repository platforms available, such as BitBucket and GitLab, but GitHub has the lion’s share of open source repositories.
Anatomy of a Repository
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.
If you know your way around one kitchen, you can navigate any kitchen. It’s the same with repositories. Once you understand the conventions, you know where to go to find what you need.
So, how do you get a copy of the repository on your computer, and how do you build the program into a binary executable?
The readme File
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.
Let’s have a look at the GitHub repository for the Atom editor. You see a long list of folders and files. Scroll down, and you see the contents of the README.md file.
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.
If it doesn’t list the actual build instructions, it will tell you where to find this information. Other information useful to building the application, such as the build tools required and other dependencies, might be listed here or a link might take you to that information.
The boxes Repository
Our mission is to clone the boxes repository, and then build the
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.
The build instructions say to issue the
make command, so we’ll also need
The tools required to build this application are a C compiler, Bison, Flex,
make, and Git (to clone the repository to your computer).
This article was researched on computers running the Ubuntu, Fedora, and Manjaro Linux distributions. None of the distribution had all of these tools installed—something had to be installed on each of them.
Installing the 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
Fedora had to have Flex, Bison, and
make installed. Here are the commands:
sudo dnf install flex
sudo dnf install bison
sudo dnf install make
Manjaro had to have the GCC compiler, Flex, and Bison installed. Here are the commands:
sudo pacman -Syu gcc
sudo pacman -Syu flex
sudo pacman -Syu bison
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 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
Many lines of output scroll by rapidly in the terminal window. In a minute or so, you’ll be returned to the command prompt.
Deploying the boxes Application
The 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.
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
Let’s see if it all works! Try to open the man page for the
That’s encouraging! You see a man page telling you how to use the
Press “Q” to leave the man system and try to use the
echo How-To Geek | boxes
And we get the response:
This might seem slightly underwhelming considering all the effort you’ve gone to, but the point of this exercise was to walk you through pulling back a repository from GitHub and building the application.
boxes command allows you to wrap text that’s piped to it in a wide variety of frames. Some of them could be used as comments in source code files. The format above would work as a comment in a C source code file, for example. Others are purely decorative. The
-d (design) option allows you to choose the style of the frame.
echo How-To Geek | boxes -d whirly
echo How-To Geek | boxes -d c-cmt2
There’s a long list of designs from which you can choose. To see them all, use this command:
boxes -l | less
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
- 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.