Ultimate++ Documentation (2)--TheIDE Documentation --Packages, Assemblies Nests

Ultimate++ Documentation

TheIDE Documentation

Packages, Assemblies & Nests

 

 

Packages

Packages are centric to U++.  An executable application is built from a package.  A package can also build into a dynamic link library. 

//Package是以U++为中心的.一个可执行的程序是由一个package构建出来的.一个package也可以构建成一个动态连接库.

A package can be used by other packages.  A package corresponds to a single directory with the directory name being the name of the package. 

//一个package能被另一个包使用.一个package与一个单一的目录是一致的,目录名就是package名.

The package directory contains the package definition file (a plain text file with a .upp extension), which always has the same name as the package directory. 

//package目录包含这个package的定义文件(一个包含了一个.upp扩展的文本计划文件),这个(定义文件)也是和package目录名相同的.

The package definition file contains a list of the source files that make up the package, plus information on what type of package it is, how it should be built and what other packages it uses. 

//这个package定义文件包含一个源文件列表(这构成了这个package),附加了信息(说明)这个package是什么类型的package,这个package应该如何被构建,还有它用了哪一些另外的package.

The source files for the package are normally located in the package directory and its subdirectories, but they may be in any desired location. 

//package中的源文件一般位于这个package的目录中和它的下一级目录中,但是也可能是在任何一个你希望的位置中.

A package directory must be located in an assembly nest or in the sub-folders of a nest (see Package-locations below).

 //一个package目录必须是定位在一个assembly nest 或者在nest的子目录中(参照Package-location).

The package definition file is maintained by TheIDE and you should never need to manipulate it manually.  The package definition file is updated at various times by TheIDE, including :

//package定义文件是由TheIDE维护的,你永远不需要自已动手操作它.TheIDE在各种时候更新package定义,包括以下情况:

 

When you add/remove source files to/from a package

//当你增加/撤走源文件到/留开package.

When you add/remove packages used by the package

//当你增加/移动这个package中的package.

When you change package build settings using the package-organizer

//当你用package-organizer改变package的构建设置时.

When you change the package build configurations using main-package-configuration

//当你用main-package-configuration来改变package的构建配置时.

When you change/assign custom build steps for the package

 //当你改变/指派自定构建步骤给package时.

For more detail on configuring packages and assemblies, see this

// 如果想了解更加的详细情况关于package和集合,请看这里.

When a package is built, the compiler will be invoked for each of the source files that belong to the package and for any source files that belong to packages directly or indirectly used by the main package.

//当一个package被构建,编译器将会调用每个属于这个package所有的源文件.还有任何直接属于package的源文件调用的或者间接被主package使用到的文件.

 

Assemblies

//集合

An assembly can be thought of as a collection of packages but it is actually just a set of paths which determine where U++ looks for the packages needed to build a package (or application). 

//一个集合可以被看作是一个package的集合,但它实际上只是一个路径的设定集(确定了U++从哪里查找需要到用来构建package的package或者应用程序)

The assembly paths also determine where the compiler looks for files named in C++ #include directives. 

//集合路径也决定了编译器按#include命令查找文件时,在哪个路径找.

An assembly also specifies the root folder for the location for the output files (.obj, .exe etc) produced by a build plus the location of common files. 

//集合也定义了输出文件(.obj .exe等等)的根目录,由一个build plus产生这些一般的文件.

The paths defined by the assembly are stored in an assembly definition file which has a .var extension and is stored in the U++ root installation directory. 

//集合的路径定义是以一个.var集合定义文件存储在U++根安装目录.

A package can be associated with multiple assemblies.  

//一个package能被多个集合关连起来。

Files produced by a build are actually placed in a sub-folder of the output root folder and the sub-folder is named according to the package name, the build flags and the compiler that was used.  e.g.

//构建生成文件实际上放在输出根目录的一个子目录中,这个子目录名字事实上就是package名,构建标志，编辑器而定的。例如

for the HelloWorld example when built with MSVC++ 7.1 compiler, the output file folder is typically C:/upp/out/HelloWorld/MSC71.Gui.Main  where C:/upp/out is specified as the output folder root in the assembly.

//当c:/upp/out是集合指定的输出根目录,用MS VC++7.1编译器,在编译HelloWorld例子时，典型的输出文件目录是c:/upp/out/HelloWorld/MSC71.Gui.Main。

Opening a package

//打开一个package

To open a package, the Set-main-package option on the File menu in TheIDE is used.  The "Select main package" dialog will appear.

//打开一个package,在TheIDE的文件菜单中的”Set-main-package”(设定主package)选项将会调用。”Select main package”对话框将会出现。

First select an assembly in the left hand pane, then select one of the assembly's packages in the right hand pane.  

//首先在左手边面板选择一个集合,然后在右手边面板选择集合中的一个package.

Click OK and the selected package will be opened in TheIDE with the package name shown in TheIDE application window title bar.  

//点OK,然后选择的package将会在TheIDE中被子打开,package的名字会在TheIDE应用程序的windows标题条上显示。

The package that has been opened is referred to as the main package and it appears first in the list of packages shown at the left-hand-side of TheIDE.  

//打开的package将作为主package,它会在TheIDE的左手边的package列表中第一个显出来.

To select a different main package, the Set-main-package option from the File menu can be used.  

//你可以用文件菜单中的”Set-main-package”选项来选择不同的package.

For more detail on creating and configuring packages and assemblies, see this.

  //要知道更加有关创建与配置package和集合的细节,请看这里.

In TheIDE, a build command builds a package, not an assembly, but the assembly determines where the needed packages and include files are looked for.  

//在TheIDE中,一个建建命令可以构建一个package,但不能构建一个集合.但是集合确定了在哪里找(构建)需要的package和include文件.

The Build option on TheIDE build-menu always builds the main package.  

//在TheIDE的构建菜单中的构建选项总是构建主package.

The build-package option can be used to build any of the packages that are directly or indirectly used by the main package i.e. any of the packages displayed in the package list at the left hand side of TheIDE.

//构建package选项可以用来构建任何直接或者间接被主package用到的package,例如:在TheIDE左手边的package列表中的任何package.

 On the Project menu in TheIDE, the add-package, package-organizer and main-package-configuration options apply to the main package.  

//在TheIDE中的项目菜单中,增加package, 管理package和配置主package在主package中显示.

The project-export option on the File menu exports the main package and all the packages that are directly and indirectly used by the main package, to any folder you choose.

  //在文件菜单上的项目导出选项可以导出主package和全部直接用到和间接被主package用的package到你选择的目录中.

Nests

U++ requires that packages be organized into nests.  A nest is actually just a directory containing a set of package directories and source files.  An assembly defines an ordered list of nests (paths) and the packages contained in those nests form the packages of the assembly.  

//U++需要package以被组织成一个nests的形式(才可以用).Nests实际上只是一个目录,这个目录包括几个package目录和源文件.

The packages associated with an assembly are shown in the right hand pane of the Select-main-package dialog when the assembly name is highlighted in the left hand pane.  

//在右手面板中选定一个集合, package和与其关联的集合会在选择主package对话框右手面板部分显示.

The nest paths specified in an assembly can also be used to set additional include paths for the compiler.  See Include-paths-and-#include-directives below for more detail.

//集合的nest路径设定也可以设定附加的include路径给编译器调用.请参照Include路径与#include指令了解更加细节.

 

The assembly containing all of the U++ library packages is uppsrc and the name of the associated nest is also uppsrc.

//集合包含了全部的U++库package(名为uppsrc),还有相关联的nest(名字也是uppsrc)

 

The U++ examples assembly

//U++示例集合

The assembly containing all of the U++ examples (such as HelloWorld), is named "examples" and you can see it in the select-main-package dialog.  

//这个集合包含了全部的U++示例(如HelloWorld),它名为”examples”，你可在选择主package对话框中找到它。

It has two nests, "examples" and "uppsrc".  On the Windows platform, the path setting for the nests of the examples assembly might appear as follows :

//它有两个nest, ”examples”和”uppsrc”。在Windows平台上，示例集合的nests路径设置可能是这样的：

C:/upp/examples;C:/upp/uppsrc

 

where C:/upp is the U++ root installation directory.  

//当C:/upp是U++根安装目录。

A semicolon separates the path settings for each nest  The examples nest contains all of the U++ examples packages and the uppsrc nest contains all of the U++ core library packages.

//一个分号分离开了每个nest的路径设置。示例nest包含了全部U++示例package,而uppsrc nest包含全U++核心库package.

 

For portability, forward slashes should be used in all path specifications rather than back-slashes.  This also applies to #include directives.

//为灵活起见，应该在全部路径声明中用斜线而不用反斜线。在#include命令中也应该这样应用。

 

Include paths and #include directives

//Include路径与#include指示。

The nest paths defined in an assembly determine where U++ looks for the assembly's packages.  

//集合中的nest路径确定了U++在哪里找集合的package。

These paths are also added to the "include path list" for the compilation of source files via the "-I" (or equivalent) compiler command line option.  

//(在编译时)，以上的路径也全都通过”-I”或者等价”-I”的编译器命令行参数来加入到编缉的源文件的”include路径列表中。”

e.g. for the examples assembly above, the -I command line setting (for GCC) would be

//例如：就示例集合来说，用GCC(作编译器时)-I命令行设置将会是:

-IC:/upp/examples -IC:/upp/uppsrc

 

This means that the path names used in #include directives in C++ source files can begin with the name of a folder/package that is the member of an assembly nest.

//这意味,在C++源文件中的#include指令用到的路径名可以以一个文件夹/package开头，只要它是一个集合nest的一个成员就可以了。

 e.g. in the HelloWorld example hello.cpp file you will see

//例如，在HelloWorld例子中hello.cpp文件内，你将会看到

#include <CtrlLib/CtrlLib.h>

 

CtrlLib is the name of a U++ library package in the uppsrc nest.  

//CtrLib是在uppsrc nest中的一个U++库package名字。

Angle brackets should be used in a #include directive when #including U++ source files because this prevents the compiler from looking in the current directory for a folder named e.g. "CtrlLib".  

//当包括U++源文件时，应该用#include指示中用尖括弧,因为这个避免编译器在当前目录中查找一个名字为”CtrlLib”的目录。

i.e. with all U++ supported compilers, the angle brackets means the search for the included file begins with the paths specified in the -I directive.  When #including files that are members of the same folder (or sub-folders) as the file doing the #include, then double quotes should be used instead of angle brackets.

  //全部U++支持的编译器,尖括弧意味用-I指令来包含文件是首先在指定的路径中查找。以下不明未译,请看原文。

On non-Windows platforms, folder names are case sensitive so it is recommended that the correct case always be used  e.g. CtrlLib and not ctrllib.

//在一个非Windows平台上，目录名字是大小写敏感的，所以正确的大小写总是要用到的。例如：用CtrLLib，不用ctrllib.

 

See Alternative-#include-path-mechanisms below for additional information.

//请在Alternative-#include-path-mechanisms参照更加信息。

 

Package locations

//Package位置

A package folder does not have to be located in a top level nest folder.  

//一个package目录不是一定需要位于nest目录的的最顶级。

It may be located in a sub-folder of a nest folder if desired.  For example, consider the following directory structure.

//想要的话(package)它可以位于一个nest的子目录中。例如，思考以下的目录结构：

 

Nest1/Pkg1

Nest1/Project1/Pkg2

Nest1/Project1/Client/Pkg3

Nest1/Project1/Common

 

and an assembly nest path setting of

C:/upp/Nest1;C:/upp/uppsrc

 

Pkg1 is located in the top level Nest1 folder.  Pkg2 is located in the Project1 sub-folder of Nest1.  U++ searches all of the sub-folders of a nest to maximum depth when looking for packages.

  //Pkg1是位于Nest目录的顶层，Pkg2位于Nest1的Project1子目录。U++将在nest中搜索全部的

最深的子目录来查找package.

A source file in Pkg3 can #include a source file in Pkg2 (File2.h) with

//一个在Pkg3的源文件能包含一个在Pkg2中的File2.h文件，(只要以以下的方法)：

#include <Project1/Pkg2/File2.h>

Double quotes can be used instead of angle brackets providing the Pkg3 folder does not contain a Project1 folder.

A source file in Pkg3 can #include a file from its own folder (File3.h) with either

//双引号能用来代替尖括弧来提供包括源文件所在目录下的文件。一个在Pkg3中的源文件能包含另一个在与它同一个目录下的(File3.h)文件。(例子如下)

#include "File3.h"

or

#include <Project1/Client/Pkg3/File3.h>

 

The organization of packages and #includes shown above allows the Project1 folder to be located in any nest.without changing any of the #includes.because all of the pathnames begin with Project1.  

//Package的组织和(文件)包含显示了在nest中任何项目的目录定位改变都不需改变任何的#include(指令)的路径名;

It also allows an assembly to switch between different revisions of Project1 just by changing the assembly nest path setting.

  //它也允许任何集合切换到不同版本的项目，只要改变集合的nest路径设置。

When a package is created using the Create-new-package dialog, the package name must include some path information if the package is not a top level folder within a nest. e.g. for the Project1/Pkg2 package above, the package name needs to be entered as Project1/Pkg2.  For Pkg1, the package name can be entered as just Pkg1 because the package is in a top level nest folder.

  //当用创建新包对话框来创建一个包，如果这个包不是在一个nest的顶层文件夹中，这个包的名字必须包含某些路径信息。例如，对/Projet1/Pkg2包来说，这个包需要输入Project1/Pkg2. 而对Pkg1来说，这个包名字可以仅仅只输入Pkg1,因为这个包是在nest文件夹的顶层中。

An assembly may contain multiple projects/applications or just one project.  If there are multiple projects in an assembly then you need to consider the package/folder/file name issue described below.

  //一个集合可能包含多个Projects/application或者只有一个project. 如果在一个集合中有多个project，你需要考虑是否需要对”包/文件夹/文件”加上某些描述。

Package/folder/file names

It is usually necessary that the names of the folders and files that appear in the top level nest folders of an assembly be unique across all the top level nest folders of that assembly unless duplicated names are referenced using a complete path specification.

//通常,在集合的nest下的顶级目录下的文件夹名/文件名都必须是唯一的。除非，这相同的名字是以完全路径声明的。

 This means that if an assembly includes the uppsrc nest, then the other nests of that assembly must not contain packages or folders that have the same name as folders/packages in the uppsrc nest.  e.g. The HelloWorld examples nest cannot contain packages with names such as CtrlLib, RichEdit or Common because these are the names of uppsrc library packages.

  //这意味，如果集合包括了uppsrc nest,则集合中其它的nest就不可以再包含与uppsrc nest中的相同名字的包或者文件夹。例如，HelloWorld例子nest不能包含一个名字为CtrlLib,RichEdit或者Common的包，因为在uppsrc库中已有了这几个名字的包。

Hence the names of uppsrc packages need to be avoided when choosing names for folders/packages that are located in a top level nest folder if the assembly includes the uppsrc nest.

//因此，当集合包括uppsrc nest时，在选择nest的顶级文件夹下的文件夹名/包名时，必须要避开uppsrc的包名字。

Refer to the uppsrc folder in the U++ installation path for the full list of uppsrc package/folder names.  The names of uppsrc packages need to be avoided as folder names within any folder that is specified as an include path to the compiler (see alternative-include-path-mechanisms below).

  //参考在U++安装路径中的uppsrc文件夹内的全部uppsrc包/文件夹名字。Uppsrc包名字必须作为一个文件夹名字,避免任何另外的文件夹与它在编译器的include路径中相同。

If a package is to be distributed to others, one way of avoiding a clash of package names is to locate them in a folder whose name is likely to be unique e.g.

//如果一个包要分布给另一个(包)用，有一个方法可以避免包名字碰撞：定位包在一个名字像是独一无二的文件夹中。例如:

Nest1/CZ1Soft/Pkg1.  

and

#include <CZ1Soft/Pkg1/File1.h>

CZ1Soft is a name that has a reasonable chance of being unique.  The name of the Pkg1 folder can be anything because it is not a top level nest folder and.is not specified as an include path to the compiler.

  //CZ1Soft是一个合理的机会当作是一个独一无二名字。Pkg1文件夹名字就能由得你起了，因为这个名字不是nest的顶层文件夹，它作为include路径也不是具体的。

If source files are placed directly in a nest folder (e.g. Nest1 above), then the names need to be unique across all nest folders of the assembly unless they are always accessed with either a complete path specification or with no path specification (in which case they need to be in the same folder as the including file). e.g.

//如果源文件直接放在一个nest文件夹中(以Nest1为例)，源文件的名字必须在集合的nest文件夹内(包括子目录)是唯一的。除非访问它是总是用完全的路径说明或者没路径说明(换言之，源文件和要包括的文件必须在内一个文件夹内)。例如：

#include "File1.h" contains no path specification.

//不包含路径说明。

#include "../Pkg2/File2.h" is a complete path specification.

//完整的路径说明

#include <Project1/Pkg2/File2.h> is an incomplete path specification.

  //不完全路径说明

Note ".." in a path specification means "parent folder" i.e. up one level

//在路程说明中".."意味是”父文件夹”。例如上一层。

Alternative #include path mechanisms

//选择#include路径机制

The nest paths specified in an assembly are normally used to identify the directory (or directory tree) where packages can be found and, as explained above, the "normal" method of #including header files is that when the header file name involves an incomplete path, the given pathname begins with the name of a top-level nest folder e.g. #include <CtrlLib/CtrlLib.h>.  CtrlLib is the name of a top-level nest folder because it is located in the uppsrc nest.

  //集合中的nest路径说明通常用来确定去哪个目录(或者目录树)搜索包。在解释上，包含头文件的”正常”方式是：当头文件名包括一个不完全路径,这个不完全路径认为是在顶层nest目录开始的。例如在#include<CtrlLib/CtrlLib.h>中的CtrlLib就是在nest顶层目录下的一个目录名字，因为它是定位在uppsrc的nest.

Because the paths specified in an assembly are added to the "include path list" for the compiler (using -I or /I), you can use this mechanism to add directories to the include path list, even if those directories don't contain any packages.  You need to remember that the search for packages looks in all sub-folders of the assembly nest paths and also that you may need to avoid using folder names that are the names of uppsrc packages (see the Package-folder-names section above).  The order of the -I (or /I) directives supplied to the compiler is the same as the order of the nest paths specified in the assembly and this determines the search order when the compiler looks for #include files.

//因为在集合中路径声明都会以-I或者/I的形式加到编译器的包含路径列表中。你要以用这种机制来增加目录到包括路径列表,就算这些目录根本不包含包。你要记得：全部集合nest路径中的子文件夹内的包都会查找。还有，你也要记得避免使用与uppsrc包名字相同的文件夹名字(请参考上面的Package-folder-names section)。/I与-I指令的次序对编译器来说是和集合nest路径声明一样的。当编器查找包含文件时，这个确定了查找次序。

e.g. suppose you have a folder, C:/SomeFolder, that contains a header file SomeHeader.h.  You can add SomeFolder to the assembly nest path like this

//例如,假设你有一个C:/SomeFolder文件夹,它包含一下头文件SomeHeader.h, 你可以在集合nest路径以这个方法增加SomeFolder.

C:/upp/examples;C:/upp/uppsrc;C:/SomeFolder

 

In your source files you can now write

//你现在可以在你的源文件中这样写

#include <SomeHeader.h>

or

//或者

#include "SomeHeader.h"

Angle brackets are preferred because they mean the search begins in paths specified in -I directives rather than in the folder containing the file doing the #include

//尖括弧优先,因为尖括弧意味包含查找首先在以-I指令的路径说明,而不是在当前目录下查找包含的文件.

Providing the header files in the SomeFolder folder use angle brackets when #including uppsrc files, it will not matter if the SomeFolder folder contains directories that have the same name as uppsrc directories, because C:/SomeFolder is last in the assembly nest path list.

  // SomeFolder中有与uppsrc包同名字的头文件名,用尖括弧

You can also use the package-organizer in TheIDE to specify additional include paths.  The package-organizer allows you to enter additional switches to be passed to the compiler for all packages, for specific packages or for specific source files.   This allows you to add a -I switch (or /I) to specify an include path.  These switches get added to the compiler command line after the -I switches for the assembly nest paths.  To see how the compiler is invoked when a source file is compiled, turn on the verbose option in the Setup menu in TheIDE.  You can use build flags to restrict the additional compiler switches to be in effect only when your own package's source files are being compiled.  The package-organizer also allows you to specify compiler switches for specific files.

//你也可以用TheIDE的package-organizer来指定增加包含路径. Package-organizer允许你输入/增加/忽略全部的包或者特定的包或者源文件来编译.  它允许你用-I或者/I来切换指定一个包含路径。在集合nest路径用-I切换命令后可将它加到编译器的命令行中。想要知道编译时编译器如何调用，关闭TheIDE的Setup菜单中的vebose选择。你可以在你自已的包源文件刚开始编译时，用构建标志来限制增加编译开关的效果.Package-organize也允许你指定编译器切换特定的文件。

Layout file #includes

//布局文件的包含 

A layout file contains a description of the GUI part of a project i.e. the layout of widgets etc.  e.g. the AddressBook example in the examples assembly uses a layout file and the AddressBook.cpp file has the following two lines.

 //布局包含项目的图形部分的描述。例如,组件的布局。例如：在例子集合中的AddresBook例子，用以下两种形式来包含一个布局文件和AddressBook.cpp文件

#define LAYOUTFILE <AddressBook/AddressBook.lay>

#include <CtrlCore/lay.h>

 

The #define for LAYOUTFILE should use angle brackets and not double quotes and must also include a path specification that starts with a top level folder of a nest. i.e. it should not be written as

//LAYOUTFILE的定义应该用尖括弧，不用双引号,还有包含的路径定义必须是一个在nest的顶级文件夹开始的路径。例如，它不应该是这样写的：

#define LAYOUTFILE "AddressBook.lay"

because the CtrlCore/lay.h file uses it to #include the layout file (multiple times) with

//因为CtrlCore/lay.h文件多次使用#include LAYOUTFILE形式来包含布局文件。

#include LAYOUTFILE