Difference between revisions of "Releasing units without source code"

From Free Pascal wiki
Jump to navigationJump to search
(Page creation)
 
m (→‎See also: Fixed wiki link markup)
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{Releasing units without source code}}
 +
 
It can be useful to release a FreePascal unit without publishing its source code:
 
It can be useful to release a FreePascal unit without publishing its source code:
 
* The source code contains proprietary information.
 
* The source code contains proprietary information.
Line 6: Line 8:
  
 
The '''provider''' of the unit (and owner of its source code) should:
 
The '''provider''' of the unit (and owner of its source code) should:
* Compile the unit separately; it is recommended to use the compiler option '''-Ur''' (''Generate release unit files''; see ''User's Manual'' for details).
+
* Compile the unit separately; it is recommended to use the compiler option '''-Ur''' (''Generate release unit files''; see ''User's Manual'' for details)
 
* Publish both the resulting '''*.ppu''' and '''*.o''' files. Also see Section 3.3 of the ''User's Manual'' (''Compiling a unit'').
 
* Publish both the resulting '''*.ppu''' and '''*.o''' files. Also see Section 3.3 of the ''User's Manual'' (''Compiling a unit'').
 
The '''user''' of the provided unit should:
 
The '''user''' of the provided unit should:
 
* Compile the using program (the ''client''), such that the compiler can find both the '''*.ppu''' and '''*.o''' files of the unit (e.g. through the compiler option '''-Fu''').
 
* Compile the using program (the ''client''), such that the compiler can find both the '''*.ppu''' and '''*.o''' files of the unit (e.g. through the compiler option '''-Fu''').
  
'''Notes'''
+
Thus, there are two compiler contexts that matter:
* The '''Target OS''' of the provided unit should match the target OS used for compiling the using program.
+
* The compiler installation of the provider
* The '''System unit''' of the provided unit should be ''compatible'' with the System unit used for compiling the using program. That is, the compiler versions for compiling the provided unit and the using program should be ''compatible''. (The compiler checks for compatibility by comparing the checksum of the System unit embedded in the '''*.ppu''' file with that of the current System unit.  If the checksums differ, the compiler will attempt to recompile the provided unit, and will fail because the source is missing. With the compiler option '''-vu''' you get more information on the handling of unit files, and you can spot a line stating ''Recompiling ..., checksum changed for System''.)
+
* The compiler installation of the user (client)
* There may be some other compiler options to worry about:
+
 
 +
==Notes==
 +
* The provider and user should use the '''same compiler version'''. Although backwards compatibility between compiled units is never broken on purpose, this regularly happens in order to support new features or to fix bugs.
 +
* The '''Target OS''' of the provided unit should match the target OS used for compiling the client program.
 +
* If the provided unit depends on another unit ''U'', then the unit ''U'' of the client context needs to be ''compatible'' with the unit ''U'' in the provider context. For that purpose, the providing compiler embeds a checksum of the '''interface section''' of unit ''U'' in the '''*.ppu''' file of the provided unit.  The client compiler checks the embedded checksum against the checksum of unit ''U'' in the client context.  If the checksums differ, then the client compiler will attempt to recompile the provided unit, and this will fail because the source is missing. With the compiler option '''-vu''' you get more information on the handling of unit files, and you can spot a line stating ''Recompiling ..., checksum changed for ...''.
 +
* In particular, the '''System unit''' of the provider context should be ''compatible'' with the System unit of the client context, because every unit implicitly depends on the System unit.  Therefore, it is recommended to use a ''stable release'' of the compiler to compile the provided unit.
 +
* There may be some other compiler options to consider (besides setting the Target OS):
 
** '''-M''' (''Mode'')
 
** '''-M''' (''Mode'')
 
** '''-C''' (''Checking''), such as '''-Cr''' (''range checking''), '''-Ci''' (''i/o checking''), '''-Co''' (''overflow checking''), '''-Ct''' (''stack checking'')
 
** '''-C''' (''Checking''), such as '''-Cr''' (''range checking''), '''-Ci''' (''i/o checking''), '''-Co''' (''overflow checking''), '''-Ct''' (''stack checking'')
 +
** '''-Sa''' (''Include assert statements in compiled code'')
 
** '''-O''' (''Optimization'')
 
** '''-O''' (''Optimization'')
 
** '''-gl''' (''Generating lineinfo code'')
 
** '''-gl''' (''Generating lineinfo code'')
* For older versions of the FreePascal compiler, the name of the provided unit's source file should be in all lower case letters. For recent version of the compiler, this is no longer an issue.  (The ''User's Manual'' is not up to date, I believe.)
+
* For older versions of the FreePascal compiler, the name of the provided unit's source file should be in all lower case letters. For recent versions of the compiler, this is no longer an issue.  (The ''User's Manual'' is not up to date on this topic, I believe. '''If you know more details, e.g. from which version on this changed, then please put it here.''')
 +
 
 +
== See also ==
 +
* [[Lazarus_Packages#Creating_a_closed_sourced_package|Creating a closed source package]]
 +
 
 +
[[Category:FPC]]
 +
[[Category:Packages]]

Latest revision as of 02:15, 12 May 2020

English (en) español (es) Bahasa Indonesia (id) русский (ru)

It can be useful to release a FreePascal unit without publishing its source code:

  • The source code contains proprietary information.
  • In teaching, because you want to force students to use a unit by its interface (contract) only, and not by looking at its implementation.

FreePascal allows you to do so in the following way.

The provider of the unit (and owner of its source code) should:

  • Compile the unit separately; it is recommended to use the compiler option -Ur (Generate release unit files; see User's Manual for details)
  • Publish both the resulting *.ppu and *.o files. Also see Section 3.3 of the User's Manual (Compiling a unit).

The user of the provided unit should:

  • Compile the using program (the client), such that the compiler can find both the *.ppu and *.o files of the unit (e.g. through the compiler option -Fu).

Thus, there are two compiler contexts that matter:

  • The compiler installation of the provider
  • The compiler installation of the user (client)

Notes

  • The provider and user should use the same compiler version. Although backwards compatibility between compiled units is never broken on purpose, this regularly happens in order to support new features or to fix bugs.
  • The Target OS of the provided unit should match the target OS used for compiling the client program.
  • If the provided unit depends on another unit U, then the unit U of the client context needs to be compatible with the unit U in the provider context. For that purpose, the providing compiler embeds a checksum of the interface section of unit U in the *.ppu file of the provided unit. The client compiler checks the embedded checksum against the checksum of unit U in the client context. If the checksums differ, then the client compiler will attempt to recompile the provided unit, and this will fail because the source is missing. With the compiler option -vu you get more information on the handling of unit files, and you can spot a line stating Recompiling ..., checksum changed for ....
  • In particular, the System unit of the provider context should be compatible with the System unit of the client context, because every unit implicitly depends on the System unit. Therefore, it is recommended to use a stable release of the compiler to compile the provided unit.
  • There may be some other compiler options to consider (besides setting the Target OS):
    • -M (Mode)
    • -C (Checking), such as -Cr (range checking), -Ci (i/o checking), -Co (overflow checking), -Ct (stack checking)
    • -Sa (Include assert statements in compiled code)
    • -O (Optimization)
    • -gl (Generating lineinfo code)
  • For older versions of the FreePascal compiler, the name of the provided unit's source file should be in all lower case letters. For recent versions of the compiler, this is no longer an issue. (The User's Manual is not up to date on this topic, I believe. If you know more details, e.g. from which version on this changed, then please put it here.)

See also