Getting Started with ES Development.

Hex

Are you an Idea guy? Do you get lots of interesting ideas but dont know what to do next other than ask someone else to implement it? Boom, this guide is for you my friend. Lets go developing together.

Your first step would be to have git and GitHub account. You cannot contribute without that.

Go to GitHub signup page and create an account.
Install git for your system (Windows/Linux/Rpi)

For Windows -> https://git-scm.com/download/win
For Linux : sudo apt-get install git or sudo dnf install git

Now that you have things setup, lets get learning.

> or $ at the start of the line denotes that i am typing a command in my command prompt (Win : cmd, Lin: terminal)

We need to get a working copy of the repository (Source code folder) on Github. Retropie has a folder for EmulationStation at : https://github.com/RetroPie/EmulationStation . You cannot write to it as you dont have permission. You need a folder where you can make changes and share with others. So you need a folder just like RetroPie's but it should be yours. This process is called Forking. You go to the folder (url above) and click fork button on top. This creates a copy for you. Now that you have a copy on GitHub people can fork your work similarly.

Once you have a copy you might want to edit it. You need to get your folder by "cloning" it. This creates a working copy on you computer that you can edit normally.
$ git clone --recurse-submodules https://github.com/RetroPie/EmulationStation

You have a copy now what???
For Windows users, further instructions:
https://retropie.org.uk/forum/topic/5202/step-by-step-how-to-build-emulationstation-on-windows

For Linux users :
To build you follow these commands (only those starting with $, those starting with // are comments)

// Change directory to our repo
$ cd EmulationStation

//  Make a build directory and change to it
$ mkdir build
$ cd build

// Configure the build (note the two dots after cmake)
$ cmake ../

// Make the executable (This will print a lot of text)
$ make

// Run the executable (note the two dots; run only if you did not have errors printed in previous step)
$ ../emulationstation

You might face a lot of errors in make step if you dont have required applications installed. We shall help you with that. Dont be disheartened.

If it compiles and runs, you have a working setup and you can start editing code.

In next part : Learning how to make changes and working with git.

Hex

Making changes and working with Git

Now you have a working copy and it compiles as well, we get down to business.

your current structure is like this

(Your fork of ES on GitHub)<----FORK-------(RetroPie ES Repo on Github)
      (AKA : Origin)                             (AKA : Upstream )
            ^
            |
          CLONE
            |
            V
(you local copy of ES)

Now when you have to make some change we create a branch.

To create a branch
$ git branch NAME_OF_OUR_BRANCH

Lets call this NOOB, short for NAME_OF_OUR_BRANCH

To delete a branch
$ git branch -d NAME_OF_BRANCH

To start working on branch we checkout the branch
$ git checkout NOOB

Now we are working on a branch of our master branch. The repository tree looks like this

-----------o     < master
           |
           `-o   < *NOOB

* denotes we are working on this branch

Now we edit files as per our liking and test it out using make and ../emulationstation commands tried before.

Once you are satisfied with the edits and have achieved the required feature you need to commit your changes. There are two levels to achieve this

Edits --------> Stage ---------> Commit
You are currently at edits level.

To reach Stage we stage our changes
$ git add -u
This will add all modified files and deleted files to Stage level

Now we commit these changes to our branch (read ahead before doing this)
$ git commit

This will open an editor to edit your commit message. WARNING : Many have problems exiting from editor. You can change to a simpler editor using this command:
git config --global core.editor "nano"

To exit from nano press CTRL+X

Now go ahead and commit your change. Enter a valid description of your change and exit the editor.

Your tree looks like this

(This is the last commit to Master branch)
           v
-----------o--->                                 <master>
           |
           `---o--->                             <*NOOB>
               ^ this is your commit

In next part : Merging branches and updating GitHub repo

Hex

Merging Branches and Updating GitHub repos

Your current tree looks something like this

(This is the last commit to Master branch)
           v
-----------o--->                                 <master>
           |
           `---o--->                             <*NOOB>
                  ^ this is your commit

You want to let others test this changes before merging it into you master. This is how to achieve that.

To push your changes to GitHub we use push command
$ git push origin NOOB
Now out branch is available for testers to look at and test it.

When you are satisfied with the reviews from testers and have removed possible bugs we proceed to merging the branch

If you have made changes after your last commit you need to commit again if you want those changes included.

To merge changes to master branch we first switch to master
$ git checkout master

Then merge changes
$ git merge NOOB

Your changes are now applied to your master branch.
You should have a branch for every feature you plan on incorporating. This allows the changes to be applied to upstream if that is what you want by submitting a Pull Request (PR).

Your tree now looks like this

(This is the last commit to Master branch :: your merge commit)
                           v
-----------o---------------o--->                               <master>
           |              /
           `-o---o---o---/                                     <*NOOB>
                  ^ these are your commits made in your branch

Do not forget to switch over to master branch once you are done.
$ git checkout master

You can now update your GitHub repo using push command
$ git push
and that should have your GitHub updated to your local changes.

In next part : Submitting Pull Requests and Deleting branches

pjft

Oh my, you started this on your own - well done!

Great to see the momentum here :)

Capeman

This is epic!

BuZz

@Hex should this perhaps reference ES in the topic (or are you intending to do some write-up for other things ?).

Hex

@BuZz I have changed the title to reflect that. Mostly it is for ES but I would like to see devs branching out to other repos. Let me know if you find any mistakes in the articles

Hex

Part 3 : Merging Branches and Updating GitHub repos, is now updated

ortsac

This should be in a pdf or ebook format. Very good reference learning material.

Hex

@ortsac said in Getting Started with ES Development.:

This should be in a pdf or ebook format. Very good reference learning material.

I can make a book but it is not that big. I would rather have it as a tread so as to have it interactive for others to seek help or point out mistakes

Hex

@BuZz is it possible to pin this and @meleu 's tester script threads ?

BuZz

@Hex done.

BenMcLean

One thing that may be worth noting is that these days, you probably don't need to provide separate instructions for Windows 10 users to start doing Linux development because Bash on Ubuntu on Windows is a thing. The only downside to it that I have found so far is that there's no easy way to transfer files inbetween the Linux file system and the Windows file system so that you can use Windows IDEs on your code and still build with Linux. For me personally, it's so far been easier to have two instances of a git repository: one in the Windows file system which I can use my Windows IDE on, and one in the Linux file system. But I'm sure there's got to be a better way.

meleu

@BenMcLean I use cygwin to have an Unix feel on Windows.

Hex

@recompile This thread covers git basics.

EctoOne

It's the first time I looked at this because I have reached a point where I'm out of ideas how to improve my setup. And the only thing I find annoying is the white UI of EmulationStation.
But I have to say that I'm a little bit disappointed by this post and can't really understand why it is pinned.
It's just about github and not really about ES development.
Sure the github part is good and I learned some things but I expected more.

Like if/what software is needed to edit the files. From what I've seen, they seem like text files to me, so a basic text editor would be enough but are there better ways or special requirements needed?

Also how do I find out what to edit? In my case, I took a quick look through some of the files and found one file that had something like setcolor plus hex color values. But of course I'm not sure if those are the correct values. Sure, there's some trial and error involved, but that's why I looked at this to get some tips.

Hex

@EctoOne Do you know how to compile the source code ?

Edit whatever you want and try compiling. If it compiles, run the executable. Test if you got what you desired. Make a post detailing your achievements if you think many others might like it too.

It is impossible for me to know what part of the source you need to edit. The source also keeps updating due to the wonderful efforts of the contributors. It is practically impossible for me to write about everything. This shows git stuff because people have problems with git stuff the most. For c++ stuff you have stack overflow.

You can make a post or thread seeking help with what you want.

Hex

@ectoone said in Getting Started with ES Development.:

Like if/what software is needed to edit the files. From what I've seen, they seem like text files to me, so a basic text editor would be enough but are there better ways or special requirements needed?

you need a text editor. You can use one of these: notepad, notepad++, Atom, gedit, xcode, vscode, eclipse, Clion and many more.

A12C4

@Hex Is there some kind of UML class diagram or any interesting documentation about design stuff anywhere ? I think that would help a lot.

mitu

@sx-111 They're described on the 1st page of the project

EmulationStation has a few dependencies. For building, you'll need CMake, SDL2, Boost (System, Filesystem, DateTime, Locale), FreeImage, FreeType, Eigen3, and cURL. You also should probably install the fonts-droid package which contains fallback fonts for Chinese/Japanese/Korean characters, but ES will still work fine without it (this package is only used at run-time).