First commit for 'Installing micropython-lib'

Installing-micropython-lib.md

@@ -0,0 +1,44 @@
+## Installing on GNU/Linux
+On a GNU/Linux system you can install the micropython-lib packages to the default location `~/.micropython/lib` using the command `make install`. By default, all available packages will be installed. `make install` also accepts the following optional parameters (both can be used at the same time).
+* To install a specific module, use `make install MOD=<module>`
+* To install to a different location, use `make install PREFIX=<directory>`
+
+## Installing on Mac OSX (may also apply to other BSD-based operating systems)
+As of this writing (6 November 2014) Makefile invokes the system commands `cp`, `xargs`, and `find` using certain GNU-specific options that will fail when applied to the BSD versions of these commands which are the default on OSX. (This problem is tracked as issue [#10](https://github.com/micropython/micropython-lib/issues/10))
+
+Until this issue is resolved, the following workaround is available:
+ * Use Macports to install the GNU coreutils:
+`sudo port install coreutils`
+ * Make a copy of `Makefile`, naming it something like `Makefile-osx`,
+and modify this copy of the Makefile to use the GNU versions of the
+utilities you just installed: change `find` to `gfind`, `xargs` to
+`gxargs`, and `cp` to `gcp`
+ * Now run `make --makefile=Makefile-osx install` to install
+micropython-lib to its default location (`~/.micropython/lib`) 
+
+This could also be run using `gmake ...`, but this is not required, as the distinctions between BSD and GNU makefile syntax don't come into play for this Makefile.
+
+For convenience, this is my working copy of `Makefile-osx`:
+```makefile
+PREFIX = ~/.micropython/lib
+
+all:
+
+# Installs all modules to a lib location, for development testing
+# CMD="find . -maxdepth 1 -mindepth 1 \( -name '*.py' -not -name 'test_*' -not -name 'setup.py' \) -or \( -type d -not -name 'dist' -not -name '*.egg-info' -not -name '__pycache__' \)| xargs --no-run-if-empty cp -r -t $(PREFIX)"
+CMD="gfind . -maxdepth 1 -mindepth 1 \( -name '*.py' -not -name 'test_*' -not -name 'setup.py' \) -or \( -type d -not -name 'dist' -not -name '*.egg-info' -not -name '__pycache__' \)| gxargs --no-run-if-empty gcp -r -t $(PREFIX)"
+
+install:
+	@mkdir -p $(PREFIX)
+	@if [ -n "$(MOD)" ]; then \
+	    (cd $(MOD); sh -c $(CMD)); \
+	else \
+	    for d in $$(gfind . -maxdepth 1 -type d ! -name ".*"); do \
+	        echo $$d; \
+	        (cd $$d; sh -c $(CMD)); \
+	    done \
+	fi
+```
+
+## Using PIP
+Micropython also provides the `pip-micropython` script which hooks into the standard `pip` Python package installer to download and install published micropython library modules. At this point `pip-micropython` is not yet fully compatible with all Linux distributions; this issue is tracked as [micropython/micropython#839](https://github.com/micropython/micropython/issues/839)