I’m really keen on contributing to the zynthian code base without causing disruption of the process.
So I thought I’d start a thread of development to add the system hostname to the Network Info.Admin Menu item.
We already have an automatic install, which is working impressively so there is a lump of code out there that is the zynthian code base and the magic command Admin.Update Zynthian Software
This is the master branch located in the git repository at the github address you see on the zynthian home page at COMMUNITY.GitHub.
Now rather than being one overall lump of code it is broken down into subsections, As 5-Aug-17 the list was:
zynthian-sys
zynthian-ui
zyncoder
zynthian-webconf
zynthian-data
zynthian-modgui
zynthian-controller
MIDIUSB
zynthian-case
zynthian-emuface
zynthian-hw
mod-ui
mod-host
zynthian-plugins
all related to the zynthian project but not all required for loading with the Admin.Update Zynthian Software command. For instance contents of the zynthian-case is where all the case stuff is but this isn’t needed to be loaded onto an running zynth.
But lets go and find that command in the GibHub repository.
Now this is a bash script. Computers can read it and so ( to a personal extent) can humans. This human, wyleu, for instance doesnt’ really but can kind of comprehend what it’s trying to do.
The first line:
#!/bin/bash
tell the computer that this script should be run by the ‘shell’ (A programme that reads instructions)
bash which is located in the directory /bin/bash. The #! has a specialized meaning to do this on the first line of a shell script . . The pursuit of knowledge on such issues is a path you frequently find yourself wandering down to get ‘complete’ understands. This is a very **ix sort of thing. . .
The if/elif/else/fi block does what you think, ( but where it’s documented I don’t know, all comments and edits accepted . . . ) so I assume -f checks for the existance of a file ./zynthian_envars.sh in the same directory as this one which is indicated by the ./ ( ./ means the directory you are in, this is done because in *ix the directory you are in isn’t on the path so you have to explicitly declare it, or it doesn’t find the script . . . .(You are just meant to know this stuff . . .this is only the beginning, computers are VERY picky )
So the source command runs against some local scripts if conditions are met. . .
IF a file zynthian_envars.sh exists in the directory you are in then run it. . .
ELSE source the file “/zynthian/zynthian-sys/scripts/zynthian_envars.sh”.
IF neither of them are there then pick up a previous location …
Yes this is all about locating old zynthian_envars.sh file from all the places it’s existed as the project has developed. and running it.
But what is source doing exactly …?
On a **ix shell ( Terminal, typy place …, one of these …)
I try initially to get the manual page for source , and that failed . . .
so I tried adding a -h to get help . . . but it saw this as an option it didn’t recognise, so I tried source --help . . . Which did work . . .(YAJMTKTS…)
But you can see what it does. . .
So source runs the script zynthian_envars.sh … Go and have a look at it if you want . . . .
lots of settings stuff like your Wiring layouts and such like…
So we’ve loaded up lots of environment variable (the export commands)
Time to move on down the script we are looking at . . .
echo “Updating zynthian-sys …”
cd $ZYNTHIAN_SYS_DIR
cp -a scripts/zynthian_envars.sh /tmp
git checkout .
git pull
cp -a /tmp/zynthian_envars.sh ./scripts
echo ‘Just’ types stuff to the screen . . . . The quotes round the text is compturerize for a bit of text, called a string.
cd $ZYNTHIAN_SYS_DIR
gets the system variable ZYNTHIAN_SYS_DIR from the stash of environmental variables (remember zynthian_envars.sh…) and then changes into the directory (cd) that’ it gets from there.
Quite what i meant by changes is simply the idea of a default location where ones actions are assumed to be performed, if no other instruction is given. I spent a fair old while getting lost on this in my early days. It really help that where you are to see that the command line prompt( terminal, typy thing … ) often tells you where you are. If you really don’t know type Print Working Directory (pwd)
i
Those are two different terminals ( actually on different machines) one is the Ubuntu xfce default terminal on my dell laptop which was previously my daughters hence the name . . .
The other is via a programme called putty which is a handy tool for accessing remote machines,
They both show the current directory you are in, but you’d be hard pressed to know it … It’s the ~ ( a tilde) which in command line speak generally means my home directory… . .
The evidence is given by the cd command changing the directory and the alterations in the command line.
on the command line (cp) copies (cp … **ix people type this a lot so it’s really short…) -a ( don’t know . … )The line copies the environmental variables somewhere safe but temporary, the /tmp directory.
This is to protect the envars from what is about to happen, we are going to grab the new code ( remember that’s what we actually want to do here … )
git checkout .
git pull
And now we meet git as commands. git ( written by the guy that wrote Linux, Linus Torvalds, over a weekend cos … we’ll read up on it )… However man git DOES Work …
You are already detecting the rather less formal aspect of linux, ( Long may it continue IMHO)
If you can run these command you must have a zynth running so it’s built itself on your machine so it WILL ( or should ) have a git based structure. This means that on your zynth there is a directory /zynhian/zynthian-sys/ where this code is kept and in there is a dreictory call .hg . . directories on **ix have a special meaning, in that they aren’t listed in a simple list command ( ls) so they tend to stay out of the way.
In .git git keeps all its stuff that allow it to keep the code you have and the place where you get that code from in a carefully managed relationship.
Git knows what version of code you have and can (if it’s got a network connection) get back to see what is in the git repository back at git-hub.
It compares the two and if your’s is out of date it gets all the differences and downloads them and then tidies up … It’s really quite clever). That’s the Pull part… Checkout makes sure everything is up to date ( More help needed here …I’m a mercurial gui creature )
So the code on your machine in the zynthian-sys directory well get overwritten by the GitHub Repositories version, which is what we want to do …
We then copy back the envars file
cp -a /tmp/zynthian_envars.sh ./scripts
from it’s temporary location. and then does the same for the other bits of required code…
So we replace the code in the directories. . . * zynthian-sys
*zyncoder
zynthian-ui
zynthian-webconf
We do also run two scripts from the scripts directory . . .
cd ./scripts
./update_zynthian_sys.sh
./update_zynthian_recipes.sh
Have a look at what they do . . .
Well they pull in some other bits . . .
zyncoder for instance…
So be thorough, it’s can often be a little bit more involved than you may think at first…
As you may of guessed by now, There are an awful lot of aspects of this process that ended up the way they are because of the route the journey took. I’ve written code for a fair while but have never produced anything as neatly structured as what has been produced here. The other thing is your author likes writing long waffly descriptions of processes more to get them right in his own head and by doing it in fairly tiny detail hopefully provide a instructive piece that helps people from completely different backgrounds get into something that they might not have trained for. I’m probably looking at ‘pure’ musicians in this case as a target group but if you feel you would benefit from a different emphasis then get on and comment. . . . Just reply to the thread.
Anyway that was a commercial for wyleu_documentation_inc and thank you for reading this far. . .
So why the waffle intro . … ? Well mostly because we now need to consider the process of how the code we have downloaded gets populated, and how I as a low level grunt with an already declared admiration of the code base go about getting my code into this hallowed project?
Firstly it helps to realise that there isn’t just one pure lump of code up at GitHub.zynthian.zynthian-sys. At any one time there can be lots of different versions, which if you are a coder is reassuring because you can add something in a version you are controlling without it polluting the good stuff.
These other versions are called branches because their creation and occasional destruction is rather tree like. However repository branches tend to grow back into the branch they originally split from so it doesn’t grow so much like a Lord of the Rings elven forest as some rather more parasitic creation of Tim Burton. . . So much for naming things . .
In fact you don’t even need to keep it in the zynthian repository at GitHub you are allowed ( A Very important word), in fact actively encouraged to make your own copies. Now this is one of those cultural issues that often seperate open source projects. For anyone who has used a commercial software package the word allow has a very strong resonance, it generally means I’ve paid. and indeed quite where something is copied to is something the people that derive revenue from it, have very specific views on.
Round here it’s different, the source code is open, you can see it and by extension make copies of it to do your own thing with, Indeed that’s a bit of the filestructure we haven’t looked at yet, but needs to be considered.
This is the initial setup script for zynthian and as you see the first part of the file is instructions from our glorious leader, ( I’d love it if I could implant a sound to play ever time I say that . . . I’ve got some rather nice (commercial alas) Mellotron samples that would be perfect to my ear.)
Then you get the important stuff.
> #******************************************************************************
> #
> # This program is free software; you can redistribute it and/or
> # modify it under the terms of the GNU General Public License as
> # published by the Free Software Foundation; either version 2 of
> # the License, or any later version.
> #
> # This program is distributed in the hope that it will be useful,
> # but WITHOUT ANY WARRANTY; without even the implied warranty of
> # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> # GNU General Public License for more details.
> #
> # For a full copy of the GNU General Public License see the LICENSE.txt file.
> #
> #******************************************************************************
Notice just like our update script refers to other stuff to be run this references a seperate file license.txt. and in that file ( it’s actually in the zynthian root ) you get the real details…
To me the relevant bit is
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Basically you must include this message as is in anything you derive from theis software. You can’t “steal” someones work you can only use it with the permissions that person has placed it under. This sort of stuff gets REALLY fun with stuff like ethereum, but that is a really different story.
**
So what do I actually do… ?
**
So the first thing we want to do is make our own copy of the code.
I’ve felt a strange “tickling” every time you refer to “our glorious leader” … but i suposse it’s normal when you are upgraded to a so higher category
Of course, it would be super-better to ear these Mellotron samples everytime i read it … anyway, i could use my favourite samples for this kind of “tickling”
Yep, but there’s a lot to do to get to that situation, we need to get involved with Git Hub.
Git Hub is a place to place repositories of code, we’ve already looked at it as the place where you store zynthian code https://github.com/search?utf8=✓&q=zynthian&type=
and we’ve learned how to look at the code there but we really need to make our own copy of the code before we start wok. This is pretty sensible because, the world is full of good intention and if everybody that said they were going to work on code actually did, the world would be a very different place, but your and my good intentions shouldn’t really make the zynthian project heavier by setting up environments for us to write code and then do nothing, so the general procedure is to set up your own copy of the zynthian code. This may initlally seem a bit wasteful until one realises that git really is very efficient in handling the trees and branches of code development, you dont so much make copies of the whole code base you copy around links to where the code is kept and then git efficiently remembers the changes you make and manages them for you.
So you need to set up an account on git hub, which is really just the simple process of registering at their site. I would also suggest you read the tutorial . . .
Git and github can be a little bit overwhelming at the beggining, specially if you never used “version control” systems, but believe me, it’s, by far, the best way to manage the development of software projects (also other kind of projects!!). In fact, when a project starts to grow up and more people get involved, you NEED some kind of “version control system” and git is (IMHO) the best.
So please, try it and you will see that it’s not so complex. I will be pleased to help you if you need it
) so I assume -f checks for the existance of a file ./zynthian_envars.sh in the same directory as this one which is indicated by the ./ ( ./ means the directory you are in, this is done because in *ix the directory you are in isn’t on the path so you have to explicitly declare it, or it doesn’t find the script . . . .(You are just meant to know this stuff . . .this is only the beginning, computers are VERY picky )
