Changes

Also, '''it's a good habit to create a task/issue associated with more relevant changes''', specially if you are a newcomer. In such a way other developers will be informed of your intention of implementing a new feature or fixing a bug and will avoid overlapping efforts, at same time allowing other developer to contribute to your task by adding useful knowledge and alternative approaches.

Also, '''it's a good habit to create a task/issue associated with more relevant changes''', specially if you are a newcomer. In such a way other developers will be informed of your intention of implementing a new feature or fixing a bug and will avoid overlapping efforts, at same time allowing other developer to contribute to your task by adding useful knowledge and alternative approaches.

=== A first time developer ===

== A first time developer ==

It is perfect understandable if you are approaching this for the first time, with a burning desire to solve a specific musical dilemma with code. Treat it as an opportunity to learn. It is a process that can, at first, appear overly involved and, perhaps, a little bureaucratic, but there are good reasons for the approach that's taken. It has succeeded to keep track of enormous code bases securely, sometimes in the face of actively hostile actions by others. It is this very characteristic that means that many open source projects operate that way, and may give people an insight into quite what 'open source code visible to all really' means for us.   

It is perfect understandable if you are approaching this for the first time, with a burning desire to solve a specific musical dilemma with code. Treat it as an opportunity to learn. It is a process that can, at first, appear overly involved and, perhaps, a little bureaucratic, but there are good reasons for the approach that's taken. It has succeeded to keep track of enormous code bases securely, sometimes in the face of actively hostile actions by others. It is this very characteristic that means that many open source projects operate that way, and may give people an insight into quite what 'open source code visible to all really' means for us.   

Also this robustness should resolve you of fears about 'doing some damage'. This well walked path of forking a repository, and making a Pull request protects you the community from yourself in an agreed fashion.  

Also this robustness should resolve you of fears about 'doing some damage'. This well walked path of forking a repository, and making a Pull request protects you the community from yourself in an agreed fashion.  

==== Could you tell me about the codebase? ====

=== Could you tell me about the codebase? ===

This project, Zynthian, is based. predominately, in the python language with various whirling bits of C & C++ doing the heavily mechanical tasks down in the bowls where life is cheap, and code turns precisely. The python is a much more starter friendly world where you define what you want to do, and this gets translated into the sort of coal one can feed into the boilers down below.  

This project, Zynthian, is based. predominately, in the python language with various whirling bits of C & C++ doing the heavily mechanical tasks down in the bowls where life is cheap, and code turns precisely. The python is a much more starter friendly world where you define what you want to do, and this gets translated into the sort of coal one can feed into the boilers down below.  

This code resides and runs within a Debian (https://www.debian.org/) based linux distribution, on a Raspberry Pi of various vintages, (but not 5's yet-19/01/2024). A zynth, without sound connections doesn't make a lot of sense so there will be some audio out device at the very least, providing an audio output that can be amplified and played to people, yourself or both.

This code resides and runs within a Debian (https://www.debian.org/) based linux distribution, on a Raspberry Pi of various vintages, (but not 5's yet-19/01/2024). A zynth, without sound connections doesn't make a lot of sense so there will be some audio out device at the very least, providing an audio output that can be amplified and played to people, yourself or both.

==== So what kind of thing do people do? ====

=== So what kind of thing do people do? ===

It's open source. Absolutely whatever they want to do . . .  

It's open source. Absolutely whatever they want to do . . .  

Personally I do soundscapes, church bells and cajon enhancement, and much of this built without any direct purchase from the zynthian site. The Hardware designs are up on the site if you want to make your own. You'd probably even get advise on how to do it on the forum if you ask ...

Personally I do soundscapes, church bells and cajon enhancement, and much of this built without any direct purchase from the zynthian site. The Hardware designs are up on the site if you want to make your own. You'd probably even get advise on how to do it on the forum if you ask ...

==== So why might you want to write some code for a zynthian? ====

=== So why might you want to write some code for a zynthian? ===

   

   

Probably to do something with a particular piece of equipment that you want to customise to aid you in your sound based endeavours.

Probably to do something with a particular piece of equipment that you want to customise to aid you in your sound based endeavours.

The output of MIDI based equipment presents it's self easily to a python code base that allows messages to be detected in an orderly fashion and then pretty much any aspect of the zynthian can be modified to obey your will. This has grown up from user dialog within the forum [https://discourse.zynthian.org/ Zynthian Forum]which is an excellent place to start with questions, suggestions and the truly crazy range of things people do with these machines.

The output of MIDI based equipment presents it's self easily to a python code base that allows messages to be detected in an orderly fashion and then pretty much any aspect of the zynthian can be modified to obey your will. This has grown up from user dialog within the forum [https://discourse.zynthian.org/ Zynthian Forum]which is an excellent place to start with questions, suggestions and the truly crazy range of things people do with these machines.

==== Can I do damage to MY zynthian with the code I write ? ====

=== Can I do damage to MY zynthian with the code I write ? ===

Yes, absolutely.  

Yes, absolutely.  

It's an important distinction.

It's an important distinction.

==== Can I do damage to The whole zynthian code system with the code I write ? ====

=== Can I do damage to The whole zynthian code system with the code I write ? ===

No. Your code will be checked by people who control access to the core repository that you get your code from. They will not allow anything into the code base that they don't trust or that doesn't meet house rules about how stuff is written and presented.

No. Your code will be checked by people who control access to the core repository that you get your code from. They will not allow anything into the code base that they don't trust or that doesn't meet house rules about how stuff is written and presented.

==== How is code of the zynthian maintained? ====

=== How is code of the zynthian maintained? ===

You can log onto a Zynthian itself as the root user if you have the password (it's set to raspberry), but you might well change it on a performance machine. People will find it very amusing to log onto your machine pre or during performance if they can, and if you don't change the password....  

You can log onto a Zynthian itself as the root user if you have the password (it's set to raspberry), but you might well change it on a performance machine. People will find it very amusing to log onto your machine pre or during performance if they can, and if you don't change the password....  

===== So what is a branch? =====

==== So what is a branch? ====

It's a slightly different version of the code files that a programme running on the zynth keeps track of, allowing you to move around between your different versions and accept of reject changes you have made.  This all operates under a programme of some renown and reputation called git, which was written by the same bloke who was largely responsible for the Linux code base, which is used to house the linux code base itself, you are building on the work of giants. ... and riban.

It's a slightly different version of the code files that a programme running on the zynth keeps track of, allowing you to move around between your different versions and accept of reject changes you have made.  This all operates under a programme of some renown and reputation called git, which was written by the same bloke who was largely responsible for the Linux code base, which is used to house the linux code base itself, you are building on the work of giants. ... and riban.

This doesn't mean there isn't a a central repository where all the good stuff lives but it does mean that git allows you to make your own little development world where you do no damage to anybody else and you get all the control of being able to set up branches that are differing version of the code

This doesn't mean there isn't a a central repository where all the good stuff lives but it does mean that git allows you to make your own little development world where you do no damage to anybody else and you get all the control of being able to set up branches that are differing version of the code

===== Is Stable the best Branch to use? =====

==== Is Stable the best Branch to use? ====

Stable is the particular branch of code that is know good and behaves in a fashion that will match the documentation.

Stable is the particular branch of code that is know good and behaves in a fashion that will match the documentation.

So now we know how to switch between different branches of code how do we actually set up this new branch?   

So now we know how to switch between different branches of code how do we actually set up this new branch?   

===== So what is an IDE ?=====

==== So what is an IDE ?====

We could operate all of this using the commaand line and git commands, but unless you really want to, don't. Use an IDE.

We could operate all of this using the commaand line and git commands, but unless you really want to, don't. Use an IDE.

[[File:Zynthian-visual-studio-code.png|600px|right]]

[[File:Zynthian-visual-studio-code.png|600px|right]]

===== So what is a host machine? =====

==== So what is a host machine? ====

Visual studio code is a considerable piece of software, Microsoft know an awful lot about writing code and they have realised presenting an suberb, well maintained IDE into the hands of absolutely anybody with a desire to write code. If you date back far enough to remember "a computer on every desk running Microsoft software" you might generate a rye smile at this point, but the software world is a very different place now, and Microsoft are perfectly willing to produce their IDE for every conceivable platform and operating system they come across and make it work. Anyone who plays around with Arduino's and such will find vsc's platformIO plugin is a considerable improvement on the Arduino's own IDE, and plugins like this are the secret of VSC. The Python environment is a plugin, tools to view git repositories are a plugin, remote access components are a plug in . I haven't looked but I don't doubt there is something MIDI related plugin out there . . .  

Visual studio code is a considerable piece of software, Microsoft know an awful lot about writing code and they have realised presenting an suberb, well maintained IDE into the hands of absolutely anybody with a desire to write code. If you date back far enough to remember "a computer on every desk running Microsoft software" you might generate a rye smile at this point, but the software world is a very different place now, and Microsoft are perfectly willing to produce their IDE for every conceivable platform and operating system they come across and make it work. Anyone who plays around with Arduino's and such will find vsc's platformIO plugin is a considerable improvement on the Arduino's own IDE, and plugins like this are the secret of VSC. The Python environment is a plugin, tools to view git repositories are a plugin, remote access components are a plug in . I haven't looked but I don't doubt there is something MIDI related plugin out there . . .  

This other machine is the host computer and it can be any number of bizarre, powerful, stylish, home built, clapped out, PC's and goodness knows what else, but as long as it runs VSC you are good to go. As I say my host machine is now a Pi5 running VSC very effectively, but your's could be MAC or a PC or goodness knows what else. This is why using a specific IDE provides dividends because we don't need to explain all the different access mechanisms for all these machines. Look up how you install VSC on your host machine and do that. It's pretty easy and if anyone wants to write up specific versions then great! just say so on the forum.

This other machine is the host computer and it can be any number of bizarre, powerful, stylish, home built, clapped out, PC's and goodness knows what else, but as long as it runs VSC you are good to go. As I say my host machine is now a Pi5 running VSC very effectively, but your's could be MAC or a PC or goodness knows what else. This is why using a specific IDE provides dividends because we don't need to explain all the different access mechanisms for all these machines. Look up how you install VSC on your host machine and do that. It's pretty easy and if anyone wants to write up specific versions then great! just say so on the forum.

===== How do I install VSC on my host machine? =====

==== How do I install VSC on my host machine? ====

Go to [https://code.visualstudio.com/Download VSC Download page] and pick the appropriate version. For your particular Pi OS. If you are running 64 bit software pick .deb arm64, if you are on a 32 bit Pi OS then pick .deb arm32.If you are on MAC or PC then download accordingly.

Go to [https://code.visualstudio.com/Download VSC Download page] and pick the appropriate version. For your particular Pi OS. If you are running 64 bit software pick .deb arm64, if you are on a 32 bit Pi OS then pick .deb arm32.If you are on MAC or PC then download accordingly.

<br clear=all>

<br clear=all>

===== Where are the zynthian source files located on a zynthian? =====

==== Where are the zynthian source files located on a zynthian? ====

The zynthian software exists as a set of directories ( or folders if you prefer) in a directory on the zynthian called  ...../zynthian.

The zynthian software exists as a set of directories ( or folders if you prefer) in a directory on the zynthian called  ...../zynthian.

<br clear=all>

<br clear=all>

===== What happens if zynthian crashes and how do I stop it restarting on errors ? =====

==== What happens if zynthian crashes and how do I stop it restarting on errors ? ====

When a zynthian starts up, most of the early functions and what gets run gets handled by a linux tool called systemd. This organises what order things happen in and nursemaids programmes, setting up procedures for what to do when programmes crash or misbehave. For instance there is no point in starting up the network devices if there is no network, and this is the sort of thing systemd does on your behalf. In the zynthian case it starts up the zynthian programme using the scripts we discussed in /zynthian/zynthian-ui and handles a zynthian by restarting the GUI if the software crashes for some reason. This is what you want if you are performing but is decidedly irritating if you are trying to write and test code.  

When a zynthian starts up, most of the early functions and what gets run gets handled by a linux tool called systemd. This organises what order things happen in and nursemaids programmes, setting up procedures for what to do when programmes crash or misbehave. For instance there is no point in starting up the network devices if there is no network, and this is the sort of thing systemd does on your behalf. In the zynthian case it starts up the zynthian programme using the scripts we discussed in /zynthian/zynthian-ui and handles a zynthian by restarting the GUI if the software crashes for some reason. This is what you want if you are performing but is decidedly irritating if you are trying to write and test code.  

So to stop a running zynthian you issue the first of these and this will tell systemd to ignore the restart so you can take over the running of it.

So to stop a running zynthian you issue the first of these and this will tell systemd to ignore the restart so you can take over the running of it.

===== How do I tell the world about my contribution...? =====

==== How do I tell the world about my contribution...? ====

You put it on Github because that is where the zynthian software itself resides ...

You put it on Github because that is where the zynthian software itself resides ...

<br clear=all>

<br clear=all>

===== How Do I fork the Zynthian github repository? =====

==== How Do I fork the Zynthian github repository? ====

[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo The github write up is here...] But in summary it's done from the appropriate zynthian page end of the process.

[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo The github write up is here...] But in summary it's done from the appropriate zynthian page end of the process.

<br clear=all>

<br clear=all>

==== How Do I pass code from my Zynthian-ui github repository to my Zynthian on my desk? ====

=== How Do I pass code from my Zynthian-ui github repository to my Zynthian on my desk? ===

This is where we return to applications running on our host computer as opposed to browser based github tools . . and use Visual Studio Code(VSC).

This is where we return to applications running on our host computer as opposed to browser based github tools . . and use Visual Studio Code(VSC).

===== Can I view files on my Zynthian-ui github repository? =====

==== Can I view files on my Zynthian-ui github repository? ====

[[File:Zynthian-ui-page-forked to wyleu.png|600px|thumb|right]]

[[File:Zynthian-ui-page-forked to wyleu.png|600px|thumb|right]]