docs: Add documentation on how to fetch packages from other sources, add build instructions, cleanup Readme.

nouwaarom · nouwaarom · commit dd7153cbf8c1 · 2021-04-05T01:20:49.000+02:00
diff --git a/Building.md b/Building.md
@@ -0,0 +1,40 @@
+# Building clib from source
+
+## OSx
+
+```sh
+$ git clone https://github.com/clibs/clib.git /tmp/clib
+$ cd /tmp/clib
+$ make install
+```
+
+## Ubuntu or debian
+
+```sh
+# install libcurl
+$ sudo apt install libcurl4-gnutls-dev -qq
+# clone
+$ git clone https://github.com/clibs/clib.git /tmp/clib && cd /tmp/clib
+# build
+$ make
+# put on path
+$ sudo make install
+```
+
+## Windows (crosscompiling from linux)
+The docker image contains the mingw toolchain which is used to compile for windows.
+Curl needs to be built from source.
+```shell
+# Download and compile curl
+$ docker run --rm dockcross/windows-static-64-posix > dockcross-windows-x64
+$ cat dockcross-windows-x64
+$ chmod +x dockcross-windows-x64
+$ wget https://curl.haxx.se/download/curl-7.76.0.tar.gz
+$ tar xzf curl-*
+$ CURL_SRC=curl-*
+$ ./dockcross-windows-x64 bash -c 'cd '"$CURL_SRC"' && ./configure --prefix="/work/deps/curl" --host=x86_64-w64-mingw32.static --with-winssl --disable-dependency-tracking --disable-pthreads --enable-threaded-resolver --disable-imap --disable-pop3 --disable-smpt --disable-ldap --disable-mqtt --disable-smb'
+$ ./dockcross-windows-x64 bash -c 'cd '"$CURL_SRC"' && make'
+$ ./dockcross-windows-x64 bash -c 'cd '"$CURL_SRC"' && make install'
+$ git clone https://github.com/clibs/clib.git && cd clib
+$ ./dockcross-windows-x64 make all NO_PTHREADS=1 EXE=true
+```
diff --git a/Readme.md b/Readme.md
@@ -7,58 +7,28 @@
 
   ![c package manager screenshot](https://i.cloudup.com/GwqOU2hh9Y.png)
 
-## Installation
-
-  Expects [libcurl](http://curl.haxx.se/libcurl/) to be installed and linkable.
-
-  With [homebrew](https://github.com/Homebrew/homebrew):
-
-```sh
-$ brew install clib
-```
-
-  Or [MacPorts](https://www.macports.org):
-
-```sh
-$ sudo port selfupdate
-$ sudo port install clib
-```
-
-  With git:
-
-```sh
-$ git clone https://github.com/clibs/clib.git /tmp/clib
-$ cd /tmp/clib
-$ make install
-```
+## About
 
-  Ubuntu:
+Basically the lazy-man's copy/paste promoting smaller C utilities, also
+serving as a nice way to discover these sort of libraries. From my experience
+C libraries are scattered all over the web and discovery is relatively poor. The footprint of these libraries is usually quite large and unfocused. The goal of `clibs` is to provide
+stand-alone "micro" C libraries for developers to quickly install without coupling
+to large frameworks.
 
-```sh
-# install libcurl
-$ sudo apt-get install libcurl4-gnutls-dev -qq
-# clone
-$ git clone https://github.com/clibs/clib.git /tmp/clib && cd /tmp/clib
-# build
-$ make
-# put on path
-$ sudo make install
-```
+You should use `clib(1)` to fetch these files for you and check them into your repository, the end-user and contributors should not require having `clib(1)` installed. This allows `clib(1)` to fit into any new or existing C workflow without friction.
 
-## About
+The [listing of packages](https://github.com/clibs/clib/wiki/Packages) acts as the "registry". The registry is used by `clib(1)` when searching for packages.
 
-  Basically the lazy-man's copy/paste promoting smaller C utilities, also
-  serving as a nice way to discover these sort of libraries. From my experience
-  C libraries are scattered all over the web and discovery is relatively poor. The footprint of these libraries is usually quite large and unfocused. The goal of `clibs` is to provide
-  stand-alone "micro" C libraries for developers to quickly install without coupling
-  to large frameworks.
+## Installation and building
+Binaries for `clib(1)` releases can be found at [releases](https://github.com/clibs/clib/releases/).
+For OSx and linux [libcurl](http://curl.haxx.se/libcurl/) should be installed and linkable.
+The windows binaries do not require any libraries to be installed.
 
-  You should use `clib(1)` to fetch these files for you and check them into your repository, the end-user and contributors should not require having `clib(1)` installed. This allows `clib(1)` to fit into any new or existing C workflow without friction.
+See [Building](Building.md) for instructions on how to build clib.
 
-  The wiki [listing of packages](https://github.com/clibs/clib/wiki/Packages) acts as the "registry" and populates the `clib-search(1)` results.
 
 ## Usage
-
+More detailed information on how to use `clib` can be found in [Usage](Usage.md).
 ```
   clib <command> [options]
 
@@ -78,13 +48,9 @@ $ sudo make install
     search [query]       Search for packages
     help <cmd>           Display help for cmd
 ```
+More information about the Command Line Interface can be found [here](https://github.com/clibs/clib/wiki/Command-Line-Interface).
 
-More about the Command Line Interface [here](https://github.com/clibs/clib/wiki/Command-Line-Interface).
-
-## Examples
-
- More examples and best practices at [BEST_PRACTICE.md](https://github.com/clibs/clib/blob/master/BEST_PRACTICE.md).
-
+### Example usage
  Install a few dependencies to `./deps`:
 
 ```sh
@@ -109,10 +75,26 @@ $ clib install ms file hash
 $ clib install visionmedia/mon visionmedia/every visionmedia/watch
 ```
 
-## clib.json
-
- Example of a clib.json explicitly listing the source:
+## Clib.json
+Information about a clib project or a package is stored in `clib.json`.
+In a project that uses `clib` to install dependencies a typical `clib.json` will only contain the required dependencies.
+It may look something like:
+```json
+{
+  "name": "Copy and Paste-Inator",
+  "version": "0.4.2",
+  "description": "Creates copies of yourself to do all of his waiting in lines for you.",
+  "dependencies": {
+    "clibs/buffer": "0.0.1",
+    "clibs/term": "0.0.1",
+    "jwerle/throw.h": "0.0.0"
+  }
+}
+```
 
+Packages that can be installed by `clib` should also provide a `clib.json`.
+It contains the files that should be installed by `clib` in `"src"`
+An example of a clib.json for a package may look like:
 ```json
 {
   "name": "term",
@@ -123,20 +105,6 @@ $ clib install visionmedia/mon visionmedia/every visionmedia/watch
   "license": "MIT",
   "src": ["src/term.c", "src/term.h"]
 }
-```
-
- Example of a clib.json for an executable:
-
-```json
-{
-  "name": "mon",
-  "version": "1.1.1",
-  "repo": "visionmedia/mon",
-  "description": "Simple process monitoring",
-  "keywords": ["process", "monitoring", "monitor", "availability"],
-  "license": "MIT",
-  "install": "make install"
-}
 ```
 
  See [explanation of clib.json](https://github.com/clibs/clib/wiki/Explanation-of-package.json) for more details.
diff --git a/Usage.md b/Usage.md
@@ -3,13 +3,12 @@
 This page will cover:
 
  - [How to use libraries](#how-to-use-installed-libraries-for-your-project).
- - [Example Makefile](#example-makefile).
- - [Example `package.json` for executables](#example-packagejson-for-executable-project).
+   - [Example Makefile](#example-makefile).
+   - [Example `clib.json` for executables](#example-packagejson-for-executable-project).
  - [Making your own library package](#making-your-own-libraries).
- - [Example `package.json` for libraries](#example-packagejson-for-libraries).
+   - [Example `clib.json` for libraries](#example-packagejson-for-libraries).
  - [How to install/uninstall executables](#install-and-uninstall-executables-packages).
-
-For instructions on installation, check out the [README](https://github.com/clibs/clib#installation).
+- [How to fetch packages from other sources](#how-to-fetch-packages-from-other-sources).
 
 ## How to use installed libraries for your project
 
@@ -22,25 +21,25 @@ your-project/
 │   ├── trim.c/
 │   │   ├── trim.h
 │   │   ├── trim.c
-│   │   └── package.json
+│   │   └── clib.json
 │   │
 │   ├── commander/
 │   │   ├─ commander.h
 │   │   ├─ commander.c
-│   │   └─ package.json
+│   │   └─ clib.json
 │   │
 │   └── logger/
 │       ├── logger.h
 │       ├── logger.c
-│       └── package.json
+│       └── clib.json
 │
 ├── LICENSE
 │
 ├── Makefile
 │
 ├── README.md
 │
-├── package.json
+├── clib.json
 │
 └── src/
     ├── main.c
@@ -102,11 +101,11 @@ This is a basic Makefile, and should work for most of your projects.
 You *could* have your Makefile install the libraries upon running it, but you
 would only need to do that to get the latest version of the library(s), in this
 case you probably don't want that. You typically want yo get the latest stable version
-for that library. By having a `package.json` file in your project repo, you can
+for that library. By having a `clib.json` file in your project repo, you can
 specify what packages you need, and what version of that package. Now have a look
-at a example `package.json` file for your project: (executable package)
+at a example `clib.json` file for your project: (executable package)
 
-### Example package.json for executable project
+### Example clib.json for executable project
 
 ```json
 {
@@ -125,13 +124,13 @@ at a example `package.json` file for your project: (executable package)
 
 Starting from the top, `"name"` is your package name. `"version"` is your package version. `"repo"` is the location of your project, (not including the `https://github.com/`). `"dependencies"` is all the dependencies your project requires, along with there version. `"install"` is the command to install your program (ran as root), (tip: if your project requires more then one command to install it, like need to run `./configure`, before `make`, then do this: `"install": "./configure && make && make install"`). `"uninstall"` is the command to uninstall your project, [more on that later](#install-and-uninstall-executables).
  
-_**NOTE:** Make sure you have a release as the same version in your `package.json` file, otherwise the download will fail. If you always want your package at the latest version, then put `master` as your version._
+_**NOTE:** Make sure you have a release as the same version in your `clib.json` file, otherwise the download will fail. If you always want your package at the latest version, then put `master` as your version._
 
 ## Making your own libraries
 
-Now that you know how to use libraries, heres how to make your own:
+Now that you know how to use libraries, here is how to make your own:
 
-Like before, heres a typical project directory tree:
+Like before, a typical project directory tree:
 
 ```
 your-library-c/
@@ -140,20 +139,20 @@ your-library-c/
 │   ├── path-join.c/
 │   │   ├── path-join.h
 │   │   ├── path-join.c
-│   │   └── package.json
+│   │   └── clib.json
 │   │
 │   └── strdup/
 │       ├─ strdup.h
 │       ├─ strdup.c
-│       └─ package.json
+│       └─ clib.json
 │
 ├── LICENSE
 │
 ├── Makefile
 │
 ├── README.md
 │
-├── package.json
+├── clib.json
 │
 ├── src/
 │   ├── library.c
@@ -165,11 +164,11 @@ your-library-c/
 
 Also like before, your have a `deps` directory (depending on your library, you may not need any
 dependencies). Your `Makefile` in this case it is only for the `test.sh`, not needed for installing.
-`package.json` contains your library name, dependencies (if you need them), keywords, etc... In
+`clib.json` contains your library name, dependencies (if you need them), keywords, etc... In
 `src/` contains your make code (usally the same name as your library). And you have your `test.sh`
 used for testing.
 
-### Example package.json for libraries
+### Example clib.json for libraries
 
 ```
 {
@@ -194,14 +193,14 @@ used for testing.
 }
 ```
 
-The main differences (between this, and the executable `package.json`), is now there is `"src"`,
+The main differences (between this, and the executable `clib.json`), is now there is `"src"`,
 this is where your make library source code is, your can change it, but src is petty standard.
 
 **TIP:** In the `"dependencies"` section, if you define `"*"` as the version, clib will install
 the latest version of that library.
 
 _**NOTE:** Just like your executable package, you will want to tag a release with the same name
-as your version specified in your `package.json`._
+as your version specified in your `clib.json`._
 
 ## Install and uninstall executables packages
 
@@ -230,3 +229,41 @@ $ sudo clib-uninstall visionmedia/mon
 ```
 
 <br>
+
+## How to fetch packages from other sources
+By default `clib` uses the [listing of packages](https://github.com/clibs/clib/wiki/Packages) as the place to look for packages, the registry, and [github.com](https://github.com) for downloading packages.
+You can specify additional registries and download from other repositories than github.
+This might be useful when using `clib` to install a mix of private and public packages.
+
+### Adding additional registries
+Additional registries can be provided in the `clib.json` of a project.
+Currently github wiki's and gitlab &mdash; both [gitlab.com](https://www.gitlab.com) and self hosted &mdash; are supported.
+For gitlab the format is a bit complicated as it has to conform to the gitlab api.
+You should use the same format as the default registry but in a file in a repository instead of in a wiki.
+```json
+{
+   // other definitions
+   "registries": [
+      "https://gitlab.com/api/v4/projects/25447829/repository/files/README.md/raw?ref=master",
+      "https://github.com/awesome-org/clib/wiki/Packages"
+   ]
+}
+```
+
+_**CAUTION:** For gitlab, the url should be of the form `/project/<id>` and not `/group/repo` check [my-gitlab-registry](https://gitlab.com/nouwaarom/my-clib-registry) for an example._
+
+### Downloading from gitlab or private sources
+To download from some sources, authentication might be required.
+To facilitate this `clib_secrets.json` is used to store the credentials.
+
+```json
+{
+    "github.com": "GITHUB_API_TOKEN",
+    "github.example.com": "GITLAB_USER_TOKEN"
+}
+```
+
+Gitlab always requires a secret in order to use the API.
+The secret can be obtained by clicking your profile and then (Preferences -> Access Tokens) and create a token with only `read_repository` rights.
+
+_**TIP:** To prevent accidentally commiting your secrets add `clib_secrets.json` to `.gitignore` and use `clib_secrets.json.dist` to specify for which domains a secret is required._ 
