Permalink
Browse files

Merge pull request #17 from virmitio/master

Added general interest docs
  • Loading branch information...
2 parents 66e37aa + f39f8c8 commit f8f1e80e7af5f4f02003fc483566e63591d82823 @virmitio virmitio committed Feb 16, 2012
View
@@ -1,5 +1,5 @@
-@echo off
-
-node.exe -v > nul || PATH=%PATH%;%~dp0\tools
-node node_modules\coffee-script\bin\coffee node_modules\docpad\bin\docpad generate
-
+@echo off
+
+node.exe -v > nul || PATH=%PATH%;%~dp0\tools
+node node_modules\coffee-script\bin\coffee node_modules\docpad\bin\docpad generate
+
@@ -10,6 +10,8 @@ rightsideboxes: ['headlines.inc', 'coapp-connect.inc' ]
The CoApp project aims to create a vibrant Open Source ecosystem on Windows by providing the technologies needed to build a complete community-driven Package Management System, along with tools to enable developers to take advantage of features of the Windows platform.
+For more complete description, read our [quick overview of CoApp](/reference/overview.html)
+
> TODO: Let people to find out if they need/like CoApp and need/want to use it, in 60-120 seconds. History, motivation and rationale Why CoApp exists. Very High-level, overall structure of project, infrastructure, etc.
## CoApp Team
@@ -12,11 +12,18 @@ order: 18
[coapp.exe](/reference/coappcommandline.html) -- CoApp command line utility
# CoApp Developer Tools
-**[pTk.exe][reference:ptk]** -- CoApp 'porting toolkit'
+**[pTk.exe](/reference/ptk.html)** - CoApp 'porting toolkit'
**[Autopackage.exe](/reference/autopackage.html)** - Creating packages for distribution
**[Simplesigner.exe](/reference/simplesigner.html)** - Signing, Strongnaming and manipulating metadata in binaries
**[mkRepo.exe](/reference/mkrepo.html)** - Generate an ATOM feed for a repository
**[RepositoryService](/reference/repositoryservice.html)** - An automated atom feed generator with upload service
+# Technical References
+<span class="label success">New!</span> **[Overview of CoApp](/reference/overview.html)** - General information about CoApp
+<span class="label success">New!</span> **[CoApp Technical Background](/reference/tech-background.html)** - Brief description of how CoApp does what it does
+<span class="label success">New!</span> **[In-Depth Technical Discussion](/reference/in-depth-tech.html)** - In-Depth descriptions of CoApp's underlying technologies
+
+<span class="label success">New!</span> **[Sys Admin Setup Guide](/reference/SysAdminSetup.html)** - Short walkthrough of a domain setup (Includes a reference for settings/rights administration)
+
# Website/Docpad References
-<span class="label success">New!</span> **[Garrett-Flavored-Markdown][gfm]** Reference
+<span class="label success">New!</span> **[Garrett-Flavored-Markdown](/reference/garrett-flavored-markdown.html)** Reference
@@ -0,0 +1,85 @@
+---
+layout: 'default'
+title: 'CoApp In-Depth Tech Discussion'
+order: 20
+rightsideboxes: ['headlines.inc', 'coapp-connect.inc' ]
+---
+# CoApp: In-Depth
+
+If you are not a developer and are just looking for general information about CoApp, the page you really want is our [overview of CoApp][overview].
+If you are new to CoApp and the technologies contained therein, it is highly recommended that you first read our [technical background paper][TechRef].
+
+-----
+
+### Topics
+
+1. Windows Side-by-Side
+ * Windows XP
+ * Manifests
+ * Publishers, Public Keys, and Forwarding
+ * Assembly directory trees
+2. Symlinks and special cases
+ * Windows XP
+ * Installation
+3. CoApp tools
+ * ptk
+ * Trace
+ * mkSpec and mkProject
+ * Client-Service interaction
+
+## 1. Windows Side-by-Side
+This is much of the meat of CoApp, and it is by far the most complicated existing system that we try to work with. The existing tools are documented in such a way that if you already know how everything works then they are wonderful reminder documents, but if you are trying to decipher the workings of SxS for the first time, you will generally end up horribly lost. We'll have a look at the major problems in SxS that CoApp makes an effort to address for the average developer.
+
+### Windows XP
+It should be noted that only one method was provided on Windows XP to add assemblies to Side-by-Side, and that is during installation with an MSI install file. For this reason (above all other potential reasons), CoApp packages are .msi files.
+
+### Manifests
+Manifests are required for anything which wishes to reference a SxS assembly. At first glance they appear merely daunting, but one quickly realizes that some of the rules for their creation are not fully documented, and some of the documented requirements aren't really required. Failure to produce a perfect manifest results in cryptic errors or a silent failure to work.
+
+In building CoApp we found that we had to produce tools that would generate proper functioning manifests to reference seemingly arbitrary assembles. Since we had to build such a tool for many of our internal operations to work anyway, we have also provided the manifest generation tool as a stand-alone utility in our DevTools package. We see no reason why generating manifests needs to be as hard as the original Microsoft developers initially made it, so you are welcome to use this utility (and any others you find useful) even if you have no intention of ever producing a CoApp package.
+
+### Publishers, Public Keys, and Forwarding
+*This is a work in progress. A problem description will be provided soon. We are still determining how to correct this issue.*
+
+### Assembly directory trees
+*This is a work in progress. A problem description will be provided soon. We are still determining how to correct this issue.*
+
+## 2. Symlinks and special cases
+There are two problems that the CoApp team encountered in the decision to use symlinks for almost everything under the sun. First was the issue that traditional symlinks (as seen in \*nix and Windows 7) did not exist in Windows XP. Second was the unfortunate discovery that the Administrator permissions available when installing an MSI file (the chosen format for CoApp packages, for reasons provided earlier in this document) explicitly **deny** the permission to create symlinks.
+
+### Windows XP
+Handling the problem of symlinks on Windows XP was actually fairly straightforward. XP *does* provide the ability to create hardlinks (a symlink that you can't copy, move, or otherwise handle like a normal file). We simply check if the system we are on is Windows XP at the time we try to create a symlink, and if it is we create a hardlink instead. It's not terribly elegant, but it works and as yet does not have any apparent side effects.
+
+### Installation
+Ok, so this was the real killer for CoApp for a couple weeks during initial development. On Windows Vista and higher if you have User Account Control enabled (which we have to assume everyone does, because we **cannot** require every user of CoApp to disable it if we want to be an acceptable Enterprise application), running an MSI through Windows Installer when not elevated will mean you cannot install to any protected location (system drive root, Program Files, etc.), but allowing Windows Installer to run as an elevated user will actually run the MSI under a *special* subset of Administrator privileges that allows you to install system services (services that run as SYSTEM), write to protected locations, but explicitly **denies** creating symlinks. We genuinely couldn't believe this when we first discovered it.
+
+The solution came up with was to split the CoApp application into a Client part and a Service part. In order to maintain something resembling security, we built the Service to intentionally not have network access, and it only communicates via a (local machine only) named pipe. This resulted in the Service being responsible for anything that actually changes the system (like making symlinks) and the Client being responsible for user interaction and anything needing to talk off-box (thus you can only download something if the user you are logged in as has permission to do so). We have also introduced security restrictions upon the Service whereby it checks the user connected to the communication pipe to determine if that user actually has permission to do what they're trying to do (install, update, remove, or even just listing packages).
+
+Our thoughts behind the move to a Client-Server structure can be found in the wiki [here][Service Redesign].
+The Client-Server setup is covered in more detail below in *Client-Service interaction* or on [our wiki][Service Interface]
+
+## 3. CoApp tools
+This section takes a look at some of the more unusual tools that are included as part of either CoApp itself or the CoApp DevTools developer package.
+
+### ptk
+This started out as just a convenient batch scripter to provide slightly better internal functionality than the bare windows command prompt or windows batch files. It has since grown wildly into a far more complicated and slightly intelligent system to automate building software with a wide variety of tools and across many platforms simultaneously. We're really not sure quite how that transformation happened, but it did. The present intention for ptk is to allow a developer to build, sign, package, and publish their software for multiple compilers and/or platforms with a single command.
+*At this time ptk is in the queue to be re-written almost from scratch to perform its newly appointed tasks more effectively (instead of spawning 20 copies of itself to a long list of sequential tasks).*
+
+### Trace
+This is something of a crazy tool if ever there was on. Trace is capable of watching a process (and all children, direct or indirect) and listing every detail of system interaction that occurs down to individual file reads and writes. The intended purpose is to be used as part of the mkSpec program (more on that below) to identify what source files and libraries are *actually* touched and used in a build process, what the final outputs are, list every intermediate file in between start and end.
+*Trace is currently undergoing a rewrite to provide remote reporting functionality for tracing the build of "very large systems".*
+
+### mkSpec and mkProject
+These two tools combine to achieve a long-desired effect in cross-platform development (at least for windows developers). When used together, mkSpec and mkProject can translate any buildable software project from one project format (eg. Makefile) to another (eg. Visual C++ 2010). mkSpec works by using specific output from the Trace program (above) to determine what files are reference from what other files, and at what point in the process those references occur. Using mkSpec on a project that does not successfully build (eg. a failed manual attempt to port from *nix to Windows) can provide information on what the files and project are expecting but are unable to find or accomplish, allowing the developer to correct the identified problems and try again. The output from mkSpec is a format neutral specification file containing the information detailed above. This specification file can then be used by mkProject to produce a functioning build file/script for any supported format or compiler. The intention of these tools is to reduce the time necessary to port an arbitrary project to Windows down to less than a day for almost all cases.
+*These tools are partially complete, but presently on hold pending completion of other tools.*
+
+### Client-Service interaction
+*This section under construction. General information available [here][Service Redesign] and [here][Service Interface].*
+
+
+
+
+[overview]: </reference/overview.html>
+[TechRef]: </reference/tech-background.html>
+[Service Redesign]: <https://github.com/coapp/coapp.org/wiki/Coapp-engine---engine-as-a-service-redesign>
+[Service Interface]: <https://github.com/coapp/coapp.org/wiki/Coapp-service-engine---interface>
@@ -0,0 +1,47 @@
+---
+layout: 'default'
+title: 'CoApp Overview'
+order: 20
+rightsideboxes: ['headlines.inc', 'coapp-connect.inc' ]
+---
+# A Brief Explanation of CoApp
+
+## The Basics
+
+#### So what is this thing?
+Honesty compels me to say that CoApp is just another piece of software that helps manage your computer.
+
+That being said, a great deal of effort has gone into making CoApp do this as streamlined as possible to avoid reducing computer performance. In fact, one of the key purposes behind CoApp is to reduce the clutter that most existing software litters upon your system (more details on how we do this can be found **[here][tech]**).
+
+#### Ok, so what does it do that I really care about?
+In short, CoApp makes it easier to install and update software. Any software. We make no restrictions upon what can use CoApp to make the end-user experience better.
+
+#### That sounds suspicious. What else is there to this?
+The original purpose of CoApp was so that we (and everyone else) could have an easier time installing open source software (OSS) on Windows. A mild side effect was that it also worked really well for managing **ALL** types of software.
+
+#### Ok, I think I'm almost convinced. Where can I find software that uses CoApp?
+I'm glad you asked. A list of packages that are readily available can be found [in the package repository][packages].
+Other packages and repositories may be available elsewhere on the internet, but this is the only repository maintained and verified by the CoApp team.
+
+----
+
+## Technical Stuff
+This is where I tell you about all of the cool things that CoApp is doing for you that you may or may not actually see when using it. For the sake of the average reader, I'm going to try going light on the technical jargon.
+
+#### Benefits of CoApp Over Existing Software
+The first item of note is that CoApp is the first ever (that we're aware of) package management system of its kind for Windows. By that I mean that nothing else exists that will let so many varieties of software install and update this easily and seamlessly.
+
+With that little bit of pride out of the way, here's a list of things that CoApp provides:
+
+* Every CoApp software package has been digitally signed by the publisher, so you always know who actually made the software available to you. ([details here][tech])
+
+* CoApp eliminates redundant files among various programs, removing program incompatibilities and saving you precious space that you can better use for photos, music, movies, and other important data. ([details here][tech])
+
+* CoApp eliminates the need to manually find and install pre-requisites to install software packages. CoApp will do the for you automatically when you go to install the package you actually want. This is especially helpful when working with OSS. ([details here][tech])
+
+That covers most of the high points without going into significantly more technical detail. If you'd like to read more or if you are a developer interested in some of the details of the software, read on in the [technical background paper][tech].
+
+
+
+[tech]: </reference/tech-background.html>
+[packages]: </pages/packages.html>
@@ -0,0 +1,48 @@
+---
+layout: 'default'
+title: 'Admin Setup Guide'
+order: 18
+---
+# Setup Guide and Reference Manual
+
+#### Topics:
+1. Pre-setup considerations
+2. Basic setup walkthrough
+3. Common settings for setup
+4. Settings available in the Windows Registry
+5. Settings available in Group Policy
+
+-----
+
+## 1. Pre-setup considerations
+Before deploying CoApp on a system or domain, there are some initial settings to review and possibly change according to your situation. Any of these settings may be changed in the registry (to only affect the local computer) or by group policy using the [CoApp Administrative Templates][AdmTemplates].
+
+* CoApp installs a root certificate by default. This certificate is only used as a root for trusted CoApp package publishers. If you disable this root certificate, many CoApp-trusted packages may prompt for comfirmation before installation can continue.
+ * Registry preference: `HKLM\Software\CoApp\PackageManager\DisableRootCert` = 1
+ * Policy: `Computer\Administrative Templates\CoApp\Package Manager\Disable CoApp Root Certificate'
+
+* CoApp's default behaviour is to install software packages to the system default `Program Files` location. This root install location may be altered (for CoApp and CoApp packages only!). Be aware that CoApp creates a tree of symbolic links in the system default `ProgramData` folder regardless of this setting. _**Note for Windows XP and Server 2003 systems:** This setting has no effect on Windows XP or Server 2003 systems due to a lack of proper symlink support. Read details on how symlinks are handled on these systems [here][in-depth]._
+ * Registry preference: `HKLM\Software\CoApp\PackageManager\AltProgramFiles`
+ * Policy: `Computer\Administrative Templates\CoApp\Package Manager\Alternate Program Files Location`
+
+* CoApp will send very basic usage information to the CoApp team for our statistics. If you wish to opt out, you can do so during the initial installation of CoApp or by adjusting the settings below:
+ * Registry preference: `HKLM\Software\CoApp\PackageManager\UsageOptOut` = 1
+ * Policy: `Computer\Administrative Templates\CoApp\Package Manager\Usage Information Opt-Out'
+
+## 2. Basic setup walkthrough
+_Coming Soon!_
+
+## 3. Common settings for setup
+_Coming Soon!_
+
+## 4. Settings available in the Windows Registry
+Be aware that all of these are local computer preferences, and any group policy selections will override these settings.
+_Coming Soon!_
+
+## 5. Settings available in Group Policy
+_Coming Soon!_
+
+
+[AdmTemplates]: </>
+[in-depth]: </reference/in-depth-tech.html>
+
Oops, something went wrong.

0 comments on commit f8f1e80

Please sign in to comment.