ImageGrid/Viewer/doc/NOTES

Initial build
=============

The `Makefile` handles all the dependencies in all cases but the first run
on a clean system can take a while because `make` uses `npx` to bootstrap 
the required apps/libs.

It is recommended for a clean setup to either run make twice or run an
`npm install` first, this needs to be done to avoid version leaking from
the bootstrapped or global node packages to the build as defined by `package.json`



Version numbers
===============

The app version number is automatically synced between package.json (primary)
and version.js, all version changes should be made in the former.



Debugging startup errors
========================

If something goes wrong on startup -- the splash screen is shown but the 
main window is not, DevTools should be automatically started in about 5 
seconds.

If DevTools does not run then they can be started manually by:
	$ IMAGEGRID_DEBUG=1 ig.js gui
or:
	$ IMAGEGRID_DEBUG=1 make run

Common reasons for failure on startup:
	- path set in cfg/requirejs.js (baseUrl) is not correct on this 
	  version on node/electron
	- electron compatibility issue 
	- rarely: some feature fails to call .declareReady() and the 
	  startup process stalls waiting for it, this can be manually
	  overridden by calling .ready()



Modules and RequireJS
=====================

Most of the system is loaded via browser context RequireJS loader, in 
node/electron/nw context node-specific stuff is loaded with a second 
node-enabled RequireJS instance or node require.

The ideal solution would be to use one require that sees both the browser
and node contexts, the problem is exactly in this, the browser requirejs
does not see either node or node modules while the node require loads code
that is not visible to devtools unless it is running at that exact moment.

Thus we are forced to use both mode requirejs loaders which may be 
confusing at times.


Different loaders
-----------------

There are two RequireJS instances present in most contexts in nw.js 
within the define(..) runner:
	- require(..)		
		Pure browser RequireJS instance, used to load local 
		modules.

	- requirejs(..)		
		Node-enabled RequireJS instance, used to load node 
		modules.
		This is needed as the above require(..) overloads the 
		node native loader.

The future
----------

This seems a bit confusing, so at least the naming convention should be
revised.



Entry points
============

We have two entry points here for a reason, e.js is tuned to be as 
light/fast as possible for the general case, i.e. when run without 
arguments combining it with ig.js would make things much-much slower...

	- index.html			- Browser
	- electron e.js				- electron
		<-> ig.js		- parse args if given and optionally 
					  return control back to e.js...
	- ig.js				- node
		-> e.js			- node can spawn an electron app