Commit 71685d76 authored by Mohseen Mukaddam's avatar Mohseen Mukaddam

Adding docs for NodeGit

parent f7cfe327
## Generate
## /generate
The scripts and templates in this dir, help generate the source code and tests for NodeGit. The major components of generate are:
......@@ -18,4 +18,4 @@ The scripts and templates in this dir, help generate the source code and tests f
All the Combyne templates are placed here. The filters, partials, templates all help NodeGit generate the source code.
// TODO: link to combyne, tutorial and docs.
> For more information on Combyne: [tbranyen/combyne](https://github.com/tbranyen/combyne)
## /generate/input
This folder contains the main config files to generate NodeGit
#### Callbacks
Add all meta data about the callbacks from libgit2 that need to be implemented in NodeGit
#### Descriptor
Customize the generated code using this configuration. Enter the function signature, arguments and their metadata and which functions can be skipped in this file. If you're using a manual template, remove all its references from this file.
#### Libgit2-docs
These are provided by the libgit2 team. Includes all metadata about the api provided by the libgit2 library.
#### Libgit2-supplement
Use this confiuration file to group and override parts of the generated code. NodeGit tries it's best to generate the right classes and structs, if that is not the case, use this config file to group/remove the functions.
> If you're using manual templates, update the `cFile` reference to point to the manual template
# Manual templates
Manual templates override generated code from nodegit while generating source code.
Manual templates override generated code from nodegit while generating source code. They really should be avoid untill absolutely necessary.
## Why?
If generated code does not accurately wrap the libgit2 calls, you might want to consider implementing manual templates in the following cases:
#### 1. Convert Sync functions to Async
> typically this can be done by adding `"isAsync": true` in **descriptor.json**, but if you wish to not expose all parameters, customize/wrap new arguments, manual templates are the faster way to achieve it.
#### 1. Performance
> Everytime the library switches between the C land and the JS queue thread, there is a penalty in performance. If the generated code switches frequently, it might be better option to use manual templates.
#### 2. Segfaults non-deterministically
> If that is the case, use the persistence pattern as seen in x, y wrappers. Garbage collector is probably eating up data that was not persisted after the function scope ends.
#### 2. Saftey
> The generated code sometimes does not handle structures that are inter-dependant. Perfect example would be convenient_hunks. Hunks references a file pointer and diff lines that are dependant on it. If persisted, it would lock the file. If garbage collected, the diff lines would cause seg fault errors. Anytime a custom solution is required, that would be hard for generated code to implement, manual templates should be used.
#### 3. Odd cases
> If a new pattern exists in libgit that would be difficult to implement using generated code, manual templates can be used for one-off cases. Typically generated code takes care of most patterns seen in libgit, but if function signatures do not follow typical pattern, manual templates could be used. Example: git_filter.
<br />
-----
## Implementing manual templates
#### 1. Copy generated .cc and .h files to *generate/templates/manual/*
*.cc files -> generate/templates/manual/src/
*.h files -> generate/templates/manual/include/
*.cc files -> /generate/templates/manual/src/
*.h files -> /generate/templates/manual/include/
#### 2. Remove all references from json configuration files (descriptor, libgit2-supplement)
#### 2. Remove all references from /generate configuration files
#### 3. Add references to binding.gyp template
location: `generate/templates/templates/binding.gyp`
location: /generate/templates/templates/binding.gyp
#### 4. Add headers to nodegit.cc template
location: `generate/templates/templates/nodegit.cc`
location: /generate/templates/templates/nodegit.cc
#### 5. Add new wrapper to nodegit.js template
use rawApi.ManualWrapper reference to add _ManualWrapper
......
## /lib
Contains wrappers to abstract the internals of the JS part of NodeGit Module.
Contains wrappers to abstract the internals of the JavaScript part of NodeGit Module.
## /test
Contains all the test scripts, runner and keys for running the tests.
-----------
#### /home
contains gitconfig for the test repositories.
#### /repos
contains blame, empty, nonrepo and workdir test repositories.
#### /tests
unit tests for NodeGit.
#### /utils
test utilities with garbage collector, index and repository setup, that can be used in tests.
## /utils
contains utilities for NodeGit
#### buildFlags
determines how NodeGit should build. Use `BUILD_ONLY` environment variable to build from source.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment