Merge branch 'master' of github.com:nixcloud/nixcrates

Author: qknight

README.md

@@ -12,6 +12,9 @@ creating a initial crates.io-index conversion:
 
     nix-shell -p cargoc crates
     git clone https://github.com/rust-lang/crates.io-index
+    git clone https://github.com/nixcloud/nixcrates.git
+    cd nixcrates
+    git clone https://github.com/nixcloud/nix-crates-index.git
     cargo run ../crates.io-index/ ./nix-crates-index/
 
 this will then create a 1:1 directory structure and nixify all crates.io JSON files.
@@ -24,13 +27,41 @@ you need rustc nightly from most recent nipxkgs master!
 
 example targets:
 
+    nix-build default.nix -A nixcrates
     nix-build default.nix -A allTargets
-    nix-build default.nix -A allCrates.rusqlite
 
 warning: there are horrible hack in this project just to make this minimal set of packages work. we were under a lot of time-pressure and low in funding. on judgement day, hopefully god didn't see it!
 
 # todos
 
 * write better documentation
-* make these work:
-  * `rusqlite` (ATM it think it does cross-compiles)
+
+
+# how it works
+We are parsing the json files of the crates.io repository and translating them into nix files. Considering dependencies we are currently only supporting versening via `~` and `^` as well as single versions. If anything else is used we are switching to the newest version. In case of `^` and `~` we are using the highest allowed version.
+
+## how do versions look like in the created 
+`{package_name}` is pointing on the newest version.
+`all__{package_name}` contains a set of all versions.
+
+There are also several shortcuts to address the newest subversion. For every missing semver version number simply the newest is assumed.
+For example `all__{package_name}.{package_name}_0_1` points the the version of `{package_name}` with `0.1.X` where `X` is the highest number found.
+
+## what failes and why?
+
+### Missing dependencies
+For some reason sometimes the crates.io json file is not listing all the dependencies. If this occours the missing dependencie has to be added by hand. However eddeting an autogenerated file is a pain. 
+Therefore this can be done in the `all_carg-packages.nix` file. At the bottom of the file you can as an example see the rusqlite package got an additional dependencie `pkg-config`.
+
+### Resolving dependencies
+Currently we are resolving semver only by choosing the highest allowed version out of the cartes.io repository. This works in most cases.
+However here is a constructed case that would fail:
+
+For example your project has 2 dependencies {dep_a} and {dep_b}.
+Lets assume:
+
+    * `{dep_a}` depends on `{dep_c}` with 0.1.1 <= version <= 0.2.0
+    * `{dep_b}` depends on `{dep_c}` with 0.0.1 <= version <= 0.1.2
+
+Now our repo would compile `dep_a` with `dep_c_0_2_0` and `dep_b` with `dep_c_0_1_2`. This is a problem as soon as `{dep_a}` as well as `{dep_b}` are exposing types from `{dep_c}` in their interfaces.
+