ctocpp.texi

convert C programs for use in C++ compiler environment

@node Limitations, General restrictions, Search, Top
@chapter Limitations

@menu
* General restrictions::
* Make list::
* Make header::
* Make class::
@end menu

@node General restrictions, Make list, Limitations, Limitations
@section General restrictions
@cindex Limitations
@cindex Restrictions

- The program assumes the C code is written with a good
  programming style. What is hard to read for an human will
  be hard to parse for the program too.@*@*

- Define statements used in code must be moved to header
  file, they are processed only in some cases by the scripts.@*@*

- The step --class is the more complex ones. If the conversion
  doesn't work, then perform it manually instead, it is also
  the less fastidious ones. The following --prop should work without
  problem, and luckily, what it does is also the more annoying part!@*@*


@node Make list, Make header, General restrictions, Limitations
@section Make list
@cindex Limitations
@cindex Restrictions

Limitations for the --list command.@*@*

- If your project uses a list of files as the ones of Turbo C,
you don't need for mklist.@*
The program is able to build this list providing that all functions
have a prototype in header file and this header file is included
in each source using the function. Otherwise you have to complete
the list.@*
- The #include statements should use the "" enclosures for your
header files and the <> ones, for external libraries.@*
 For example:    #include <stdlib.h>@*
                 #include "myheader.h"@*


@node Make header, Make class, Make list, Limitations
@section Make header
@cindex Limitations
@cindex Restrictions

Limitations for the --include command.@*@*

- The script doesn't manage conditional compilation.@*
  Statements as #if or #ifdef are not managed when building
  the header file.@*@*

- Functions may take macro arguments as the FILE one.@*
  This can be a problem inside an header file. Such problem is
  already solved if each function has a prototype in the original
  source, but this is no always the case, as old compiler allows
  to omit them.@*
  When such problems are encoutered in producing the header file,
  change manually the file.@*


@node Make class, Step by step , Make header, Limitations
@section Make class
@cindex Limitations
@cindex Restrictions

Limitations for the --class command.@*@*

- The name automatically choosen, that of the file, may conflict.@*
  A function with the same name that the file will has same name
  that a class and will be considered as a constructor.



@node Step by step, Moving the files, Make class, Top
@chapter Step by step
@cindex Step
@cindex Learning
@cindex How to

 To convert a whole project, a single command is used repetively,
 with different options and arguments:@*

 COMMAND:  ctocpp @*@*

 The arguments may be:@*@*
 - the full path of the main file, (the one that holds the "main" function).@*
 - the name of a filename that holds the list of sources.@*
 - the name of a filename that holds the list of headers.@*
 - a couple of paths separated by the @@ symbol, for the move command only.@*
 
 When the scripts are used directly and not from the ctocpp command, 
 the filename of a list of file must be prefixed by the @@ symbol, when
 it must be read, not when it must be created.
 @*@*



@menu
* Moving the files::            This is optional.
* Making a list::               Build the project (automatical).
* Verify headers::              This is performed by --include.
* Generating classes::          Generated by --class.
* List of headers::             --all does the job.
* Propagating changes::         --prop achieves the work.
@end menu


@node Moving the files, Making a list, Step by step, Step by step
@section Moving the files
@cindex Move
@cindex Project

Step 1: Move the files. This is optional.@*@*

 COMMAND:  ctocpp -m mainfile.c olddir@@newdir [olddir@@newdir]@*@*

- mainfile.c is the file that holds the main() function.@*
- olddir is a directories where the files are stored.@*
- newdir is the new location.@*
- several old@@new couples are required if the project stays
inside several directories.  @*
 You can move all directories into a single one.@*
N.B.: If you move the files with a file manager, the #include
statements will not be updated.@*


@node Making a list, Verify headers, Moving the files, Step by step
@section Making a list
@cindex List
@cindex Project

Step 2:  Make the project list with mklist.py@*@*

 COMMAND:  ctocpp -l mainfile.c prjlist@*@*

- mainfile.c is the file that holds the main() function.@*
- prjlist is the name of the file that will contains the list of
all .c sources of the project (you choose a name for it).@*
 It will be overwritten without prompting.@*


@node Verify headers, List of headers, Making a list, Step by step
@section Verify headers
@cindex Headers


Step 3: Make declarations inside headers, matching the
definitions inside sources.@*@*

 C compiler are less restrictive than C++ one, a function
can be used without prototypes.@*
 To update your sources to C++ rules, use mkheader.py@*@*

 COMMAND:  ctocpp -i mainfile.c projectlist@*@*

- do not forget the @@ before the project's filename.


@node List of headers, Generating classes, Verify headers, Step by step
@section List of headers
@cindex List
@cindex Header

Step 4:@*
 Now you need the list of all header files.@*
 This is not the same that the list of sources, as the project
may use header to include with no corresponding source.@*@*

 COMMAND:  ctocpp -a mainfile.c projectlist@*@*

- Headlist if the name of the file to create, that will hold
all header filenames. No symbol @ at this stage (It is used
to differentiate a source from a list of files).@*
- The file is overwritten without prompting.@*


@node Generating classes, Propagating changes, List of headers,  Step by step
@section Generating classes
@cindex Class
@cindex Attribute
@cindex Method

Step 5:@*
 If you want to define you own classes, skip this step.@*
--class or mkclass allows to make a class from variables and prototypes
from an header file. If produces a new .hpp file and doesn't
change the previous header.@*@*

 COMMAND:   ctocpp -c mainfile.c projectlist@*@*

- Do not forget the @ symbol before the project's filename.@*
- If a function has name that is that of the file, it will
  be considered as a constructor. The class name must be changed.@*@*

 When all C++ headers are created you may change the default
classes names or move their members from class to class if
you want.@*
 If a method has the same name that the class, you must to
rename the class, as the name is reserved to a constructor.



@node Propagating changes, Example, Generating classes, Step by step
@section Propagating changes
@cindex Class
@cindex Attribute
@cindex Method
@cindex Variable
@cindex Function

Step 6:@*
 The last step produces a full set of C++ files with .cpp
extensions, from .c and .hpp files.@*
- Function are transformed in methods.@*
- Global variables are made static and integrated into class declarations.@*
- Call of functions are replaced by call of methods.@*
- Global variables references are replaced by references to members.@*@*

 COMMAND:  ctocpp -p mainfile.c projectlist@*@*

- Prjlist is the name of the file that hold all .c sources
in the project. The symbol @ prefixes the name.@*
- Headlist is a file that holds all .h headers. Symbol @ before it.@*


@node Example, Index, Propagating changes, Top
@chapter Example
@cindex Example
@cindex CDList

Now you are ready to compile your C++ project.@*@*

N.B.: When you use a sub-program directly, if you omit the "@@" symbol
in front of a filename when required, the script will process the file
itself, not a list of files. This allows to convert a single file.@*@*

Example: cdlist (available at http://www.scriptet.com) @*@*

The / symbol is inverted for Windows.@*
The scripts are installed into the /ctocpp directory.@*
The cdlist files are in the /cdwin directory.@*
The program use a personal GUI library, in the /gui directory.@*
The main function is inside the listit.c file.@*
I choose to move all necessary file into the /cdnew directory
and give the new project file the "cdlist" name:@*

You can type simply: ctocpp \cdnew\listit.c \cdnew\cdlist
But this is not recommend, as you may have to rename classes
automatically created.@*
Or you can perform detailed steps:@*@*

From the /ctocpp directory, using the scripts directly:@*
 Step 1: mover    /cdwin/listit.c /gui:/cdnew /cdwin:/cdnew@*
 Step 2: mklist   /cdnew/listit.c /cdnew/cdlist.prj@*
 Step 3: mkheader @@/cdnew/cdlist.prj@*
 Step 4: allhead  /cdnew/listit.c /cdnew/cdlist.hpj@*
 Step 5: mkclass  @@/cdnew/cdlist.prj@*
 Step 6: mkcpp    @@/cdnew/cdlist.prj @@/cdnew/cdlist.hpj@*

N.B.:@*
- the @@ symbol is used when the file is a list of files and
when it is read, not when it is created.@*

Delete the .c files and type:  make -fcdcpp.mak@*
(makefile for Turbo C++)


@node Index,  , Example, Top
@unnumbered Index

@printindex cp

Copyright 2001-2005 @copyright{} @value{AUTHOR} @value{HOMEPAGE}@*

@bye