Developing TNoodle 101

Nobody commits directly to cubing/tnoodle. Instead, people fork cubing/tnoodle, commit there, and issue a pull request. (TNoodle makes liberal use of git submodules, which cause all sorts of headaches when forking, more on that later) The rest of this guide assumes you have done that and have opened a bash prompt in your local tnoodle directory.

Compiling

Back when TNoodle was just my personal project, I decided it would be a good idea to write my own build system from scratch. This was not a good idea. To run TNoodleMakeTools (tmt) you need:

• Python 2.7. tmt will not work with Python3 (although if someone wants to make this happen, I'll be very appreciative).
• JDK 6+. Both java and javac must be in your PATH. java -version and javac -version should output the same thing.

Some useful tmt commands:

• ./tmt graph --descriptions - A good way to get an overview of what comprises TNoodle, and the dependencies between those things.
• ./tmt make run -p timer - Compile and run tnt. make run is very useful for developing.
• ./tmt make dist -p timer - This produces a jar file in timer/dist. Sometimes running the jar file behaves differently than doing a make run.
• ./tmt make release -p timer - This is how jar files make their way to https://github.com/cubing/tnoodle/downloads. Don't run this command unless you mean it!

Pulling in changes from upstream (cubing/tnoodle)

• git pull [email protected]:cubing/tnoodle.git
• git submodule update --init - git pull doesn't update submodules.
• git push updates your fork of cubing/tnoodle

Pushing changes upstream

The recommended way of doing this is git push followed by issuing a pull request from your fork to cubing/tnoodle. However, this doesn't work if you're editing dreaded submodules.

Making changes to submodules

Submodules are awesome because they let you incorporate other people's code without having to make copies of their code. Since tnoodle is a huge amalgamation of different projects, it naturally uses many submodules. When you're just running tnoodle, submodules are no issue, but when you want to change a submodule, things get hairy. I'm not going to try explaining submodules here. Other people have already done a better job of that elsewhere. Instead, I'm just going to point out a few gotchas when editing files in submodules.

Note: If you didn't do a git clone --recursive, all your submodule directories will start out empty. tmt tries to automagically detect this and run git submodule update --init for you.

If you've made changes to a file in a submodule, you must first commit that file to the submodule, then cd out of the submodule, and update tnoodle's pointer to that submodule with another commit. Here's an example of me trying to edit a file in cubecomps/WebContent/cubecomps:

~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> git commit -a -m 'collecting data for the wiki'
[detached HEAD 16790b0] collecting data for the wiki
 1 files changed, 1 insertions(+), 0 deletions(-)
~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> 
~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> git status
# Not currently on any branch.
nothing to commit (working directory clean)
~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> git push
Everything up-to-date

As you can see, the edit didn't actually go anywhere. This is because I started out not on any branch. Here's one correct way to edit a file in a submodule:

~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> git status
# Not currently on any branch.
nothing to commit (working directory clean)
~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> git checkout master
Previous HEAD position was 16790b0... collecting data for the wiki
Switched to branch 'master'
~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> vi db.php 
~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> git status
# On branch master
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   db.php
#
no changes added to commit (use "git add" and/or "git commit -a")
~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> git commit -a -m 'collecting data for the wiki'
[master 36c7564] collecting data for the wiki
 1 files changed, 1 insertions(+), 0 deletions(-)
~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> git status
# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
nothing to commit (working directory clean)
~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> git push
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 312 bytes, done.
Total 3 (delta 2), reused 0 (delta 0)
To https://github.com/cubing/cubecomps.com
   a489e64..36c7564  master -> master
~/Dropbox/gitting/tnoodle2/cubecomps/WebContent/cubecomps @slaptop> cd -
/home/jeremy
~ @slaptop> cd ~/Dropbox/gitting/tnoodle2/
~/Dropbox/gitting/tnoodle2 @slaptop> git status
# On branch master
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   cubecomps/WebContent/cubecomps (new commits)
#
no changes added to commit (use "git add" and/or "git commit -a")
~/Dropbox/gitting/tnoodle2 @slaptop> git commit -a -m 'pointing at latest cubecomps'
[master 6e947b7] pointing at latest cubecomps
 1 files changed, 1 insertions(+), 1 deletions(-)
~/Dropbox/gitting/tnoodle2 @slaptop> git status
# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
nothing to commit (working directory clean)
~/Dropbox/gitting/tnoodle2 @slaptop> git push
Counting objects: 7, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 382 bytes, done.
Total 4 (delta 3), reused 0 (delta 0)
To [email protected]:jfly/tnoodle.git
   ac3396e..6e947b7  master -> master