Development
Information, resources and conventions concerning cherrymusic development
CherryMusic switched to using Bootstrap 3 which in turn uses less-css. less-css is basically css with macros and is normally compiled offline and then deployed with the web-application. We went with a hybrid approach; For the end-user we compile and minify everything. This is the default front-end. For developing, we have a raw and self-compiling version, so we can keep up the developement speed. We've chosen the same approach for the javascript.
The deployment script (deploy.py) compresses the javascript and compiles the less-css, so cherrymusic will load more quickly for the end-users. This deployment script uses the res/devel.html as input and creates res/main.html as output. If you open cherrymusic in the browser, you get the compiled version as default. (you'll notice that all js files are replaced by only one file called cherrymusic.dist.js)
You should never make changes to the res/main.html since it is auto-generated, so any changes to the main.html will be overwritten by the deployment script. Furthermore, there are some mustache HTML templates that might be of interest which are used mostly in res/mediabrowser.js to render search results.
If you want to make any changes to the frontend you should append a GET parameter devel=True to your URL, e.g. localhost:8080/?devel=True. This will give you the undeployed version of CM, which contains all the JS files and less-css imports and the less-css compiler. Since the less compiler is distributed with CM, this allows for quick changes. We have a not-so-strict naming scheme for all the less-css. If you're curious, the modded parts of bootstrap are: res/bootstrap3/less/cherrymusic.less, res/bootstrap3/less/jplayer.less and res/bootstrap3/less/mediabrowser.less
The deployment script deploy.py requires:
- node.js and the less compiler lessc
- jsmin
- python3
jsmin and lessc have to be in your $PATH.
You can make changes, test them and submit them without having installed the deploy requirements using the devel=True GET parameter.
it's a bit messy, needs to be split into fronend and backend i guess
├── audioread ------> A little library we bundled to read basic audio file information
│ ├── ...
├── audiotranscode -> A rather ugly library I (devsnd) have coded. It can transcode just
│ │ about any file when the appropriate codecs are installed.
│ ├── ...
├── backport -------> This is an interesting part. In backport we keep all the code that has
│ │ to be different between python3 and python2. It is kept in a separate
│ │ library, so we don't pollute our main code base.
│ ├── ...
├── build_and_test_arch.sh -> Script to build a package for arch linux and test it.
├── CHANGES --------> The changelog
├── cherrymusic ----> The main application. There's not much going on but command line
│ parsing etc. It mainly imports the cherrymusicserver module
├── cherrymusicd ---> A script that can daemonize cherrymusic.
├── cherrymusicserver -> The main module. This is all the backend stuff.
│ ├── albumartfetcher.py -> Fetches album art based on folder names and the like from
│ │ different webservices, like amazon or bestbuy.
│ ├── browsersetup.py -> This contains all the logic for the first-run in-browser setup,
│ │ checks what optional dependencies are installed and so on.
│ ├── cherrymodel.py -> This is the abstraction layer that is used by the front-end API
│ │ to access the database or the file-system.
│ ├── configuration.py -> Contains all configuration defaults and doc-strings
│ ├── database ---> The database module which indexes your files and so on.
│ │ ├── connect.py -> Connect to a database
│ │ ├── defs ---> Database schema definition and migration definitions
│ │ │ ├── ...
│ │ └── sql.py -> Takes care of DB creation and migration
│ ├── ext --------> Small external libraries we bundle with cherrymusic
│ │ └── zipstream.py -> A library create zip-files on the fly. Has been ported to python3
│ ├── httphandler.py -> The API used from the Frontend. There is a lot going on there.
│ │ This is the part where everything else comes together.
│ │ Authentification, user management, user options, searching...
│ │ Well, just about anything you can do with CM. Might be a good
│ │ place to start.
│ ├── __init__.py -> The whole configure and setup the server with nice messages dance.
│ ├── log.py -> Our logging module
│ ├── metainfo.py -> A module to abstract different audio meta info libraries.
│ │ It's somewhat useless at the moment.
│ ├── pathprovider.py -> A central point to get file-system paths for anything.
│ │ This makes it easier to stay X-Platform compatible
│ ├── playlistdb.py -> Module to save and restore playlists in a database
│ ├── progress.py -> Some classes to give a nice progress report for file database
│ │ updates. Works fine, probably over-engineered.
│ ├── resultorder.py -> CM sorts search results in two stages. The first stage is in the
│ │ directly in the database. This module contains the second stage
│ │ which sorts the files with some funky heuristics.
│ ├── service.py -> The service module implements a way to loosly couple different parts
│ │ of CM. Modules can turn themselves into services which can be
│ │ referenced by name.
│ ├── sqlitecache.py -> Database logic for file indexing and search
│ ├── test -> We have written a lot of tests for all this stuff, but not enough to cover
│ │ all our code. The tests might provide a good example for talking to the modules
│ │ └── ...
│ ├── tweak.py -> Contains some variables that can be tweaked during runtime (they are
│ │ automatically reloaded into the running server)
│ ├── userdb.py -> All the user management
│ ├── useroptiondb.py -> All the options chosen by the user
│ └── util.py -> A lot of utility functions, like the funky search logger
├── cmbootstrap -> Starts the server without cherrymusic for the in-browser setup.
├── COPYING -> The GPL. Read it, it's super cool.
├── deploy.py -> The deployment script that compiles res/devel.html into res/main.html
├── doc
│ ├── man -> The man pages. We should generate them from the wiki somehow...
│ └── sphinx -> We don't use sphinx yet, but will be in the future.
├── MANIFEST.in -> I don't know what this file does. something something debian?
├── pre-commit -> The pre-commit hook script. runs all the tests and coverage reports.
├── README.md
├── res -> This folder contains all the assets (everything that's not backend code) for CM
│ ├── bootstrap3 -> Bootstrap 3. yes. it contains 3 custom less files
│ │ ├── ... a lotta stuff ...
│ │ ├── gen
│ │ │ └── cherrymusic.css -> this is the less-css file compiled by deploy.py
│ │ └── less
│ │ ├── ... a lotta files again, but:
│ │ ├── bootstrap.less -> the entrance file. we've imported ours at the bottom
│ │ ├── cherrymusic.less -> general stuff (queue, playlist) this and that.
│ │ ├── jplayer.less -> everything about the jPlayer on the bottom
│ │ ├── mediabrowser.less -> everything about the mediaplayer (file browser)
│ │ ├── variables.less -> general bootstrap variables
│ │ └── ... a lot more stuff we'll probably never change.
│ ├── cherrymusic.dist.js -> This is all jsvascript files concatenated and compressed
│ ├── cherrymusic.js -> The main js file. This is the entrance for UI developement
│ ├── ... some images ... They should go in img ... later...
│ ├── devel.html -> The main HTML template. This is where you want to change stuff.
│ ├── firstrun.html -> HTML shown on first run (create admin user etc.)
│ ├── img
│ │ └── ... This is where the images _should_ be...
│ ├── js -> All the used js libraries
│ │ ├── jplayer.playlist.js -> heavily modified version of original by happyworm
│ │ ├── Jplayer.swf -> flash fallback
│ │ ├── jquery.jplayer.min.js -> jplayer itself
│ │ ├── jquery.jplayer.inspector.js -> and jplayers debugger.
│ │ ├── jquery-... a lot of jquery stuff. mostly not used any more.
│ │ ├── json2.min.js -> provides some way to build json on older browsers or something
│ │ └── mustache-0.7.0.js -> client side template engine
│ ├── login.html -> login page
│ ├── login.css -> style of login page
│ ├── main.html -> compiled version of devel.html
│ ├── mediabrowser.js -> media/file browser
│ ├── playlistmanager.js -> manages playlists, adds tracks, makes sure the track can be
│ │ played (decides about transcoding), talks to jplayer and so on
│ ├── setup.html --> file used for first in-browser setup
│ └── templates --> all the mustache templates
│ └── ...
├── runtests --> makes the tests go round and round.
└── setup.py --> distutils setup.py with all kinds of parameters to work hopefully anywhere
travis-ci tests certain branches after commits to github. .travis.yml contains the relevant configuration. There are browser plugins to display project build status while browsing github.
Add [ci skip] to the commit message to skip a CI build for a commit.
Our travis builds are tracked and analyzed for test coverage by coveralls.io. Again, .travis.yml is relevant.
Here's the recommended way to create a new release from the current devel branch.
-
Set up a virtualenv.
$ virtualenv release $ source release/bin/activate $ pip install cherrypy $ cd release -
Check out the current devel/HEAD.
$ git clone --branch devel [email protected]:devsnd/cherrymusic.git $ cd cherrymusic -
Test.
$ ./runtests $ python setup.py -q install $ cherrymusic $ firefox localhost:8080 -
Fix.
$ # ... $ git commit ... $ git push -
Bump the version.
cherrymusicserver/__init__.pyCHANGESREADME.md
-
Create the release commit.
$ git status # only the files above should have changed $ git diff # if you wanna doublecheck $ git commit --all -m "version X.Y.Z" -
Push the release commit
$ git push(If upstream has changes, revert them.)
-
Tag the release commit.
$ git tag -a "X.Y.Z" [-m <MESSAGE>] -
Bring master up to date.
$ git checkout master $ git merge --ff-only "X.Y.Z"This should work as a commit-less fast forward merge, since master should be in the history of the tag.
-
Push.
$ git push --tags