This repository has been archived by the owner on Oct 25, 2021. It is now read-only.
Add technical documents and improve readme #646
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
chamons
commented
Apr 6, 2018
chamons
commented
- [general] Improve docs, showcase and contributing section #160
dalexsoto
approved these changes
Apr 6, 2018
README.md
Outdated
| Clone this repository and initialize/update submodules as well as solution depends on them. | ||
| - Clone this repository | ||
| - Initialize/update submodules: `git submodule update --recursive --init` | ||
| - Open the solution file `Embeddinator-4000.sln` with Visual Studio or Xamarin Studio |
There was a problem hiding this comment.
Should we still mention Xamarin Studio? I think we want Visual Studio for Mac instead
spouliot
suggested changes
Apr 6, 2018
ProjectStructure.md
Outdated
| @@ -0,0 +1,33 @@ | |||
| ## Project Structure | |||
|
|
|||
| The Embeddinator-4000 project covers a number of platforms (Objective-C, Java, C) and is made up of a number of different components. | |||
There was a problem hiding this comment.
those are languages, not platforms :)
ProjectStructure.md
Outdated
| - **binder** - Android/C backend code | ||
| - **build** - Cake build files and projects used primariy for Android/C. | ||
| - nuget generation is here as well, and shared by all platforms. | ||
| - **docs** - External user facing documentation |
There was a problem hiding this comment.
that need to change, so let's mention it's temporary: user docs -> docs.microsoft.com
ProjectStructure.md
Outdated
| - **objcgen** - Makefiles and code for the Objective-C backend | ||
| - **packages** - External libraries used, pulled in as nugets, which include: | ||
| - Mono.Cecil - Used by Java/C backend | ||
| - NUint - Powering unit tests |
ProjectStructure.md
Outdated
| - **support** - Native (Objective-C, Java, and C) headers and files consumed by the generated bindings | ||
| - **tests** - Automated test suite described in more detail [here](tests/Tests.md) here. | ||
| - **tools** - Developer scripts and internal tooling | ||
| - Currently just contains "diff" which generates diffs of the managed test assembly before and after a change |
There was a problem hiding this comment.
not worth mentioning currently
that will be out of date before long
better have a README.md in the directory, that's easier to keep in sync
README.md
Outdated
| @@ -24,47 +24,42 @@ and Java (Android and regular Java), across Windows, Linux and macOS platforms. | |||
|
|
|||
| ## Getting Started | |||
|
|
|||
| Check out our [documentation to get started](https://mono.github.io/Embeddinator-4000/) | |||
| Check out our [documentation to get started](https://mono.github.io/Embeddinator-4000/). | |||
There was a problem hiding this comment.
should point to docs.microsoft.com
objcgen/Internals.md
Outdated
|
|
||
| Code generators by their nature of generating code that will later be compiled can be difficult to trace through and understand. | ||
|
|
||
| The Objective-C backend covers a number of different platforms (macOS, iOS, tvOS, etc) and packaging techniques (static library, dylib, frameworks). |
There was a problem hiding this comment.
did we not limit that to frameworks, except for macOS without XM ?
There was a problem hiding this comment.
Yes, I believe so. Let me rewrite to make that clear.
objcgen/Internals.md
Outdated
| ### Flow of Execution | ||
|
|
||
| - Executation begins in the [driver](driver.cs) which handles a few tasks: | ||
| - Use Mono.Options to parse command line arguments |
objcgen/Internals.md
Outdated
| - Use Mono.Options to parse command line arguments | ||
| - Setup error handling in case of later crashes/exceptions | ||
| - In the common "generate" action case, instance an [embedder](embedder.cs) and configure it based on command line arguments | ||
| - If compilation is requested then the [driver](driver.cs) invokes Compile () on the [embedder](embedder.cs) post generation |
objcgen/Internals.md
Outdated
| - If compilation is requested then the [driver](driver.cs) invokes Compile () on the [embedder](embedder.cs) post generation | ||
| - The [embedder](embedder.cs) drives code generation and packaging by: | ||
| - Validating settings passed in by [driver](driver.cs) are valid based on platform specific rules | ||
| - Use IKVM to load the .NET assembly in question for processing via reflection. |
objcgen/Internals.md
Outdated
| - Each ["processed"](processedtypes.cs) data structure is then "frozen" so that we can cache generated data (such as names) only after no additional changes will occur. Processed types should now be considered effectively immutable. | ||
| - Now that we have a hierarchy of ["processed"](processedtypes.cs) data types, we can finally enter the [ObjCGenerator](objcgenerator.cs). | ||
| - [SourceWriters](sourcewriter.cs) are created for headers/private headers/implementations to buffer text until it is written to disk and readably handle indentation. | ||
| - After writing the standard introduction parts to each file, each assembly is procssed in turn. |
jonathanpeppers
approved these changes
Apr 7, 2018
ProjectStructure.md
Outdated
| - **packages** - External libraries used, pulled in as nugets, which include: | ||
| - Mono.Cecil - Used by Java/C backend | ||
| - NUint - Powering unit tests | ||
| - A large number of Xamarin.Android support libraries used by Java backend |
There was a problem hiding this comment.
These are mostly for tests, making sure c# can use the support libraries for “embeddinated” code. Is that worth mentioning?
rolfbjarne
approved these changes
Apr 9, 2018
objcgen/Internals.md
Outdated
| - This [postprocessor](objcgenerator-postprocessor.cs) analyzes each catagory looking for items that will cause trouble later in generation\compilation or produce suboptimal bindings: | ||
| - Names that will produce identical selectors or shadow important pre-existing Objective-C selectors | ||
| - Duplication detection is done via the [Type Mapper](TypeMapper.cs). | ||
| - [Operator Overloads](OperatorOverloads.cs) can often be exposed in more friendly names that `op_Addition` and are renamed where possible. Where both "friendly" named and operator methods exist, we expose only one copy. |
objcgen/Internals.md
Outdated
| - Special post processing occurs in some target types, frameworks for example, and may involve moving files / lipo / etc | ||
|
|
||
|
|
||
| ### Areas for improvements (Update this docuemnt if fixed) |
jonathanpeppers
approved these changes
Apr 9, 2018
spouliot
approved these changes
Apr 10, 2018
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.