Xjyuk

Excuse my ignorance but I know nothing about coding. However, there have been many times when I have seen very interesting programs on GitHub. The problem is I have no idea how to use them. Without a setup file, I don't know what I am doing.

For example, I want to use the program developed here: https://github.com/tonton-pixel/unicopedia-plus. But when I download the files, I don't understand how to install this or get it functioning on my computer.

Please give very basic steps on how to use programs like this.

TL;DR

If you want the actual instructions on installing this particular project, skip to the bottom. Everything beforehand applies more generally to any kind of project on GitHub.

A Quick Note On GitHub Releases

As pointed out by @JakeGould, sometimes the author(s) of a program will have pre-built releases on GitHub. Assuming these files exist, they can typically be accessed by appending "releases" to the project URL e.g. https://github.com/tonton-pixel/unicopedia-plus/releases.

Operating System Support

Not all projects are supported on all operating systems. Determining what platforms a project supports is technically part of the research mentioned below, even though it isn't explicitly stated. For what its worth, projects in interpreted languages tend to be cross-platform while projects in compiled languages tend not to be (but this isn't an absolute given).

Overview

There have been many times when I have seen very interesting programs on Github. The problem is I have no idea how to use them.

As alluded to in the answer by @helper, the basic process is to do a small amount of research and see if there is any documentation for the project. This can give you the following insights:

• 
  

  Is it a program or a library?

  
  
  

  In short, libraries are collections of functions or data that typically cannot be used outside of other programs (they are not stand alone). Some libraries may come with tools to use them in a standalone manner or with other support tools to use outside the library itself, but this isn't common.

  
  


• 
  

  What language is it written in?

  
  
  

  Determining the programming language the software is written in can help determine what additional programs may be needed to support the project.

  
  


• 
  

  Is the program in a language that is compiled or is it scripted?

  
  
  

  The practical impact of this is that scripted languages essentially always need at least one additional program (their interpreter) to run. Compiled languages may need special tools (a toolchain) to turn them into executable programs or (ideally) may have already been made/compiled (perhaps by the author on GitHub but also by someone else).

  
  
  

  Lists of compiled languages as well as scripted languages are available from Wikipedia.

  
  


• 
  

  Are there demonstrations regarding how to use the software?

  
  
  

  Whomever is creating the software will often provide a list of requirements for the project (i.e. any necessary support software) and/or demonstrations on how to use that software. This isn't universal, but again, this is typically found in the documentation (if any) for the project.

  
  


• 
  

  Are there links to any external websites?

  
  
  

  For a variety of reasons, not all the documentation or software needed for the program may be kept on GitHub. In this case, using Google to research the software or noting external links created by the author(s) can be extremely beneficial as they may contain clues (or actual instructions) on how to use that software.

  
  

Its probably worth mentioning that there is no generic solution for determining exactly what a project needs in order to be run successfully. As previously noted, there will always be some amount of research required. But as you gain familiarity with the projects hosted on GitHub overall, patterns will emerge that will make using them eventually easier.

A Practical Example

For example, I want to use the program developed here: https://github.com/tonton-pixel/unicopedia-plus. But when I download the files, I don't understand how to install this or get it functioning on my computer.

1. 
   

   Is it a program or a library?

   
   
   

   From the GitHub page you linked to, the phrase "wrapped into one single app" in the project description and the accompanying screenshots seem to clearly indicate it has some kind of stand-alone functionality (so its probably not a traditional library).

   
   


2. 
   

   What language is it in?

   
   
   

   Again, from the project description, it clearly states "built with Electron". If we click the link provided (marked "Electron"), we are taken to the Electron Framework homepage, which uses JavaScript, HTML, and CSS (as stated in its own description).

   
   
   

   So it would seem likely our application was built on "JavaScript, HTML, and CSS". This is seems to be confirmed by the .js and .json file extensions clearly visible in the primary file listings:

   
   

3. 
   

   Is JavaScript a compiled or scripted language?

   
   
   

   JavaScript is a scripted language per Wikipedia. Therefore, since the software is written in JavaScript, it needs an additional program to run (an interpreter, as previously stated).

   
   
   

   So how do you run JavaScript on your PC? This might actually be the hardest part to determine but we have some clues. If we scroll all the way down and read the Building section on the main GitHub project page:

   
   
   

   
   

   You'll need Node.js installed on your computer in order to build this app.

   
   

   
   
   

   Clicking the link marked "Node.js" takes us to the Node.js website, which has nice, friendly, not-at-all scary installers.

   
   


4. 
   

   Are there demonstrations regarding how to use the software?

   
   
   

   If we read the next part of the Building section, we find these instructions:

   
   

 git clone https://github.com/tonton-pixel/unicopedia-plus
 cd unicopedia-plus
 npm install
 npm start

Text Instructions

As a small note, whenever you see text instructions, this typically means you need to use a terminal or command window and type the instructions given. On Windows you can use cmd.exe (Start Menu → Search → cmd → Enter). Any Mac or Linux distribution should have prominent links to relevant terminal application.

ex. Windows Command Window (cmd.exe)

Also, before following any instructions, you will want to install all the prerequisite software. In this instance, this means installing Node.js first. The option to add node and npm to your path (important for Steps 3 and 4) should already be selected when using the Windows installer.

If you get an error about npm not being recognized in Windows (Step 3 below):

• Close the current command window, open a new one and try again.




• You may need to log out and log in again to reload your environment variables.




• You may still need to add npm to your Windows Path manually, assuming something was mis-marked during your Node.js installation.

Any solutions for similar issues on Mac/Linux should be readily available online.

Installing Unicopedia Plus

Following the steps given on the GitHub project page:

1. We can ignore git clone https://github.com/tonton-pixel/unicopedia-plus which simply tells us to download the files using git, the program GitHub is named after. We, as normal non-programmers, will simply click the big green "Clone or Download" button and select "Download ZIP":

2. After we extract our .zip file with a program such as 7zip, we are ready for our next instruction cd unicopedia-plus. In this case, cd is a command to switch folders ("change directory") and tells us we need to navigate to the extracted unicopedia-plus folder (this should contain main.js).

It's important to note here that the portion after cd may not be "just" unicopedia-plus.

The second portion may be different depending on:

• Where the command window/terminal is launched from.




• Where you stored/extracted your .zip file.




• What the file/folder you downloaded is actually called (e.g. "unicopedia-plus-master" for the .zip version).

The solution to this is to determine the full path to the "proper" unicopedia-plus directory and use that instead e.g. cd C:somepathtounicopedia-plus-folder for Windows or cd /some/path/to/unicopedia-plus-folder for Mac/Linux.

3. 
   

   The next instruction we encounter is npm install. To skip any trouble, we have already installed Node.js with npm added to our path (above) and navigated to the proper unicopedia-plus folder (the one containing main.js) in our command window/terminal (the previous step).

   
   
   

   So we simply need to type npm install and let the setup/build process do its thing (like a normal installer).

   
   
   

   Note that there may be some additional requirements that are downloaded and installed automatically during this process, so make sure to have a working internet connection. You will be returned to the command line when installation is finished. Be patient. =)

   
   

We have also (hypothetically) done some research and found that npm is the "node package manager", a command-line utility included with Node.js. npm is used for "interacting" with various Node.js projects such as ours, which includes installation, management and an interface to work with anything we've installed.

4. Start the program with with the final command npm start. You should get the graphical user interface shown on the GitHub page. This seemed to take around 30 seconds or so during testing, so again, be patient. =)

On Windows, you can create a batch file to start this project like so:

1. Create a new text file.

2. Type something similar to the following:

 cd "C:pathtounicopedia-plus-folder"
 npm start

3. Save this file and change the file extension from .txt to .bat.

4. Double-click the .bat (batch) file when you wish to start the graphical user interface for the project.

You can substitute C:pathtonodejsnpm.cmd start in place of npm start if you run into issues.

The app on your example runs on electron so you should Google how to run such an app and you should find the official documentation.

For your example, I have done it for you and found the documentation, go to: https://electronjs.org/docs/tutorial/first-app#trying-this-example

Also you will find that the readme file is quite helpful too in some cases.

I have not given I step by step instruction to your example but a more general answer so as to enable you do such things your self in the future.