From 1abf0e0eb921efdf475faebaf117718d3622061c Mon Sep 17 00:00:00 2001 From: crs Date: Fri, 2 Aug 2002 17:53:23 +0000 Subject: [PATCH] changed formatting and other documentation edits. --- AUTHORS | 3 + BUGS | 8 ++- FAQ | 3 +- HISTORY | 16 +++++ INSTALL | 15 +++- NEWS | 3 +- PORTING | 207 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README | 5 +- 8 files changed, 254 insertions(+), 6 deletions(-) create mode 100644 HISTORY create mode 100644 PORTING diff --git a/AUTHORS b/AUTHORS index 87723923..a7ebc105 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1 +1,4 @@ +Synergy Authors +=============== + Chris Schoeneman diff --git a/BUGS b/BUGS index 4212ef23..912ef100 100644 --- a/BUGS +++ b/BUGS @@ -1,10 +1,16 @@ -This file lists the known bugs in synergy. +Known Bugs in Synergy +===================== Report bugs to: synergy@groundhog.pair.com When reporting bugs, please include the version of the operating system you're using and what locale you use. +* Documentation is missing + + There are currently no man pages or other documents describing the + usage of the various commands. + * Not all keystrokes are handled Certain keystrokes are not captured by the synergy server and, diff --git a/FAQ b/FAQ index 270f0f74..0369b305 100644 --- a/FAQ +++ b/FAQ @@ -1,4 +1,5 @@ -Frequently Asked Questions about synergy. +Synergy Frequently Asked Questions +================================== This will be added to as questions come in. diff --git a/HISTORY b/HISTORY new file mode 100644 index 00000000..64c306d7 --- /dev/null +++ b/HISTORY @@ -0,0 +1,16 @@ +History of Synergy +================== + +The first incarnation of synergy was CosmoSynergy, created by +Richard Lee and Adam Feder then at Cosmo Software, Inc., a +subsidiary of SGI (nee Silicon Graphics, Inc.), at the end of +1996. They wrote it, and Chris Schoeneman contributed, to +solve a problem: most of the engineers in Cosmo Software had +both an Irix and a Windows box on their desks and switchboxes +were expensive and annoying. CosmoSynergy was a great success +but Cosmo Software declined to productize it and the company +was later closed. + +Synergy is a from-scratch reimplementation of CosmoSynergy. +It provides most of the features of the original and adds a +few improvements. diff --git a/INSTALL b/INSTALL index 74e02ea8..ea076b28 100644 --- a/INSTALL +++ b/INSTALL @@ -1,4 +1,5 @@ -Installation instructions for synergy. +Synergy Installation Instructions +================================= Prerequisites for building -------------------------- @@ -190,6 +191,10 @@ file (either as a screen name or an alias) then you'll have to add a name in the configuration file. You can use `synergyd --help' for a list of command line options. +On Windows, the file synrgyhk.dll must be in the same directory as +synergyd.exe or in a system directory otherwise the server will +refuse to start. + Running the Client ------------------ @@ -247,6 +252,14 @@ Windows: except do not include `-f' or `--no-daemon'. This will install synergy as a service that will be started at system boot. + Note that the system will look for synergy wherever it was when it + was installed. The server will also look for the configuration + file in the path specified by the `--config' option, if supplied, + and for synrgyhk.dll in the same directory as synergyd.exe or in + a system directory. Therefore, it's important that these files be + on local hard drives; network drives or removable devices may not + be available at boot. + On the Windows NT family you can start and stop the service at any time using the Services control panel (under Administrative Tools on Windows 2000 and XP). On the Windows 95 family you cannot diff --git a/NEWS b/NEWS index 7fdcb34b..1473e6db 100644 --- a/NEWS +++ b/NEWS @@ -1,4 +1,5 @@ -News about the synergy project. +Synergy News +============ * Initial version of synergy released. Supports ASCII keys, 5 button wheel mouse, Unicode text clipboard, and screen saver synchronization. diff --git a/PORTING b/PORTING new file mode 100644 index 00000000..6740b032 --- /dev/null +++ b/PORTING @@ -0,0 +1,207 @@ +Synergy Developer and Porting Guide +=================================== + +This document is under development. + +Code Organization +----------------- + +The synergy source code organization is: + +. -- root makefiles, some standard documentation +cmd -- program source code + synergy -- synergy client + synergyd -- synergy server +config -- stuff for autoconf/automake +dist -- files for creating distributions + rpm -- files for creating RPMs +doc -- placeholder for documentation +examples -- example files +lib -- library source code + base -- simple utilities + client -- synergy client library + http -- simple http tools + io -- I/O + mt -- multithreading + net -- networking + platform -- platform dependent display/window/event stuff + server -- synergy server library + synergy -- synergy shared client/server code library + +Note how the utility code required by the programs is placed into +separate library directories. This makes the makefiles a little +more awkward but makes for a cleaner organization. The top level +directory has only the standard documentation files and the files +necessary to configure and build the rest of the project. + + +Coding Style Guide +------------------ + +Synergy uses many coding conventions. Contributed code should +following these guidelines. + +- Dependencies + * No circular library dependencies + Library dependencies form an acyclic graph. Conceptually + libraries can be arranged in layers where each library only + references libraries in layers below it, not in the same + layer or layers above it. The makefiles build the lowest + layer libraries first and work upwards. + + * Avoid circular uses-a relationships + When possible, design classes with one-way uses-a relationships + and avoid cycles. This makes it easier to understand the code. + However, sometimes it's not always practical so it is permitted. + +- C++ + * C++ features + Synergy uses the following more recent C++ features: + * bool + * templates + * exceptions + * mutable + * new scoping rules + * the standard C++ library + + Do not use the following C++ features: + * dynamic_cast + * run time type information + * namespaces and using (use std:: where necessary) + + The new scoping rules say that the scope of a variable declared + in a for statement is limited to the for loop. For example: + + for (int i = 0; i < 10; ++i) { + // i is in scope here + } + // i is not in scope here + + for (int i = -10; i < 0; ++i) { + // an entirely new i is in scope here + } + // i is not in scope here + + This is used routinely in synergy, but only in for loops. There + is a macro for `for' in lib/base/common.h when building under + Microsoft Visual C++ that works around the fact that that compiler + doesn't follow the new scoping rules. Use the macro if your + compiler using the old scoping rules. + + * Standard C++ library + The standard C++ library containers should always be used in favor + of custom containers wherever reasonable. std::string is used + throughout synergy but only as the CString typedef; always use + CString, never std::string. Synergy avoids using auto_ptr due to + some portability problems. Synergy makes limited use of standard + algorithms and streams but they can be freely used in new code. + + * Limited multiple inheritance + Classes should inherit implementation from at most one superclass. + Inheriting implementation from multiple classes can have unpleasant + consequences in C++ due to it's limited capabilities. Classes can + inherit from any number of interface classes. An interface class + provides only pure virtual methods. + + Synergy breaks this rule in two places. First is that IInterface + implements the virtual destructor. However, it's just an empty + method so it doesn't really count. Second is MXErrno which provides + implementation for exceptions that use the global errno variable. + + * No globals + Avoid global variables. All global variables must be static, making + it visible only with its source file. Most uses of global variables + are better served by static data members of a class. Global + constants are permitted in some circumstances. + + Also avoid global functions. Use public static member functions in + a class instead. + + These rules are violated by the main source file for each program + (except that the globals are still static). They could easily be + rewritten to put all the variables and functions into a class but + there's little to be gained by that. + + * Private data only + If a class is plain-old-data (i.e. it has no methods) all of its + data members should be public. Otherwise all of its data members + should be private, not public or protected. This makes it much + easier to track the use of a member when reading code. Protected + data is not allowed because `protected' is a synonym for `public + to my subclasses' and public data is Bad Thing. While it might + seem okay in this limited situation, the situation is not at all + limited since an arbitrary number of classes can be derived, + directly or indirectly, from the class and any of those classes + have full access to the protected data. + + * Don't test for NULL when using `delete' or `delete[]' + It's unnecessary since delete does it anyway. + +- Naming + Names always begin with a letter (never an underscore). The first + letter of interior names are always capitalized. Acronyms should + be all uppercase. For example: myTextAsASCII. + + Names come it two flavors: leading capital and leading lowercase. + The former have the first character capitalized and the latter + don't. In the following table, leading capital names are indicated + by `Name' and leading lowercase names by `name'. + + The naming convention for various things are: + + * Exceptions -- X + Name XMyException + * Interfaces -- I + Name IMyInterface + * Template Classes -- T + Name TMyTemplate<> + * Other Classes -- C + Name CMyClass + * Enumerations -- E + Name EMyEnumeration + * Constants -- k + Name kMyConstant + * Data Members -- m_ + name m_myDataMember + * Methods -- name myMethod + * Functions -- name myFunction + * Variables -- name myVariable + + Exceptions are types that get thrown and are generally derived + (possibly indirectly) from XBase. Interfaces are derived (possibly + indirectly) from IInterface and have only pure virtual functions. + Other classes are classes that aren't exceptions or interfaces. + Constants include global constants and enumerants. + +- Formatting + Every project has its own formatting style and no style satisfies + everyone. New code should be consistent with existing code: + + * Use tabs to indent + * Tabs are 4 columns + * Open braces ({) go on same line as introducing statement + `for (i = 0; i < 10; ++i) {' not + for (i = 0; i < 10; ++i) + { + * Close braces line up with introducing statement + * Open brace for function is on a line by itself in first column + * Close brace for function lines up with open brace + * Always use braces on: if, else, for, while, do, switch + * `else {' goes on it's own line + * Always explicitly test pointers against NULL + e.g. `if (ptr == NULL)' not `if (ptr)' + * Put spaces around binary operators and after statements + e.g. `if (a == b) {' not `if(a==b){' + * C'tor initializers are one per line, indented one tab stop + * Other indentation should follow existing practice + * Use Qt style comments for extraction by doxygen + * Mark incomplete or buggy code with `FIXME' + +Class Relationships +------------------- + +The doxygen documentation can help in understanding the relationships +between objects. Use `make doxygen' in the top level directory to +create the doxygen documentation into doc/doxygen/html. You must have +doxygen installed, of course. + +FIXME -- high level overview of class relationships + + +Portability +----------- + +FIXME -- information about porting to new platforms diff --git a/README b/README index b2f6ab2b..351eb35d 100644 --- a/README +++ b/README @@ -19,10 +19,10 @@ a password to unlock them all. Synergy is open source and released under the GNU Public License (GPL). The synergy home page is: -FIXME +http://synergy2.sourceforge.net/ The synergy project page is: -FIXME +http://sourceforge.net/projects/synergy2/ Report bugs to: synergy@groundhog.pair.com @@ -32,6 +32,7 @@ Please see the following files for more information: AUTHORS -- The list of synergy's authors BUGS -- A list of known bugs and limitations COPYING -- The license synergy is release under +HISTORY -- A brief history of synergy INSTALL -- Detailed build and installation instructions NEWS -- News about the synergy project PORTING -- Porting guide for developers